You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by rc...@apache.org on 2024/07/04 04:13:17 UTC
(james-project) 01/02: [Antora] Make partial for server configure section & clean format
This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch postgresql
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit e0aebc2f5017e13e15ca6019d78734b61ce25365
Author: Tung Tran <vt...@linagora.com>
AuthorDate: Mon Jul 1 08:25:14 2024 +0700
[Antora] Make partial for server configure section & clean format
---
.../pages/distributed/configure/batchsizes.adoc | 33 +-
.../pages/distributed/configure/blobstore.adoc | 182 +----------
.../distributed/configure/collecting-contacts.adoc | 39 +--
.../distributed/configure/collecting-events.adoc | 69 +---
.../servers/pages/distributed/configure/dns.adoc | 54 +---
.../pages/distributed/configure/domainlist.adoc | 44 +--
.../pages/distributed/configure/droplists.adoc | 32 +-
.../servers/pages/distributed/configure/dsn.adoc | 219 +------------
.../pages/distributed/configure/extensions.adoc | 61 +---
.../pages/distributed/configure/healthcheck.adoc | 24 +-
.../servers/pages/distributed/configure/imap.adoc | 182 +----------
.../servers/pages/distributed/configure/index.adoc | 88 +----
.../servers/pages/distributed/configure/jmap.adoc | 185 +----------
.../servers/pages/distributed/configure/jmx.adoc | 66 +---
.../servers/pages/distributed/configure/jvm.adoc | 104 +-----
.../pages/distributed/configure/listeners.adoc | 157 +--------
.../distributed/configure/mailetcontainer.adoc | 96 +-----
.../pages/distributed/configure/mailets.adoc | 149 +--------
.../distributed/configure/mailrepositorystore.adoc | 40 +--
.../pages/distributed/configure/matchers.adoc | 169 +---------
.../pages/distributed/configure/opensearch.adoc | 313 +-----------------
.../servers/pages/distributed/configure/pop3.adoc | 78 +----
.../servers/pages/distributed/configure/queue.adoc | 18 +-
.../pages/distributed/configure/rabbitmq.adoc | 172 +---------
.../configure/recipientrewritetable.adoc | 19 +-
.../servers/pages/distributed/configure/redis.adoc | 30 +-
.../configure/remote-delivery-error-handling.adoc | 119 +------
.../pages/distributed/configure/search.adoc | 17 +-
.../servers/pages/distributed/configure/sieve.adoc | 93 +-----
.../pages/distributed/configure/smtp-hooks.adoc | 353 +--------------------
.../servers/pages/distributed/configure/smtp.adoc | 317 +-----------------
.../servers/pages/distributed/configure/spam.adoc | 192 +----------
.../servers/pages/distributed/configure/ssl.adoc | 248 +--------------
.../servers/pages/distributed/configure/tika.adoc | 50 +--
.../distributed/configure/usersrepository.adoc | 123 +------
.../servers/pages/distributed/configure/vault.adoc | 34 +-
.../pages/distributed/configure/webadmin.adoc | 101 +-----
.../configure/batchsizes.adoc | 5 +-
.../configure/blobstore.adoc | 81 +----
.../configure/collecting-contacts.adoc | 3 +-
.../configure/collecting-events.adoc | 3 +-
.../distributed => partials}/configure/dns.adoc | 5 +-
.../configure/domainlist.adoc | 5 +-
.../configure/droplists.adoc | 6 +-
.../distributed => partials}/configure/dsn.adoc | 31 +-
.../configure/extensions.adoc | 7 +-
.../configure/forCoreComponentsPartial.adoc | 15 +
.../partials/configure/forExtensionsPartial.adoc | 14 +
.../partials/configure/forProtocolsPartial.adoc | 15 +
.../configure/forStorageDependenciesPartial.adoc | 11 +
.../configure/healthcheck.adoc | 5 +-
.../distributed => partials}/configure/imap.adoc | 7 +-
.../distributed => partials}/configure/jmap.adoc | 9 +-
.../distributed => partials}/configure/jmx.adoc | 5 +-
.../distributed => partials}/configure/jvm.adoc | 3 -
.../configure/listeners.adoc | 33 +-
.../configure/mailetcontainer.adoc | 15 +-
.../configure/mailets.adoc | 5 +-
.../partials/configure/mailrepositorystore.adoc | 34 ++
.../configure/matchers.adoc | 6 +-
.../configure/opensearch.adoc | 65 ++--
.../distributed => partials}/configure/pop3.adoc | 7 +-
.../distributed => partials}/configure/queue.adoc | 3 -
.../configure/rabbitmq.adoc | 54 +---
.../partials/configure/recipientrewritetable.adoc | 15 +
.../distributed => partials}/configure/redis.adoc | 3 -
.../configure/remote-delivery-error-handling.adoc | 44 +--
.../distributed => partials}/configure/search.adoc | 3 -
.../distributed => partials}/configure/sieve.adoc | 7 +-
.../configure/smtp-hooks.adoc | 44 ++-
.../distributed => partials}/configure/smtp.adoc | 15 +-
.../distributed => partials}/configure/spam.adoc | 17 +-
.../distributed => partials}/configure/ssl.adoc | 16 +-
.../configure/systemPropertiesPartial.adoc | 23 ++
.../distributed => partials}/configure/tika.adoc | 3 -
.../configure/usersrepository.adoc | 12 +-
.../distributed => partials}/configure/vault.adoc | 13 +-
.../configure/webadmin.adoc | 18 +-
78 files changed, 450 insertions(+), 4505 deletions(-)
diff --git a/docs/modules/servers/pages/distributed/configure/batchsizes.adoc b/docs/modules/servers/pages/distributed/configure/batchsizes.adoc
index 4d6123e468..be7e6bfb1c 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 0ebcf516d5..84673e86b4 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 <a href="/server/config-vault">configuring deleted messages vault</a>).
-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 ed00b04d24..418700ad92 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 :
-
-....
-<mailet match="SenderIsLocal" class="ContactExtractor">
- <attribute>extractedContacts</attribute>
-</mailet>
-<mailet match="All" class="AmqpForwardAttribute">
- <uri>amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}</uri>
- <exchange>collector:email</exchange>
- <attribute>extractedContacts</attribute>
-</mailet>
-
-....
-
-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 f103a76a23..0d8532bf17 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 :
-
-....
-<!-- ICAL pipeline -->
-<mailet match="All" class="StripAttachment">
- <mimeType>text/calendar</mimeType>
- <attribute>rawIcalendar</attribute>
-</mailet>
-<mailet match="All" class="MimeDecodingMailet">
- <attribute>rawIcalendar</attribute>
-</mailet>
-<mailet match="All" class="ICalendarParser">
- <sourceAttribute>rawIcalendar</sourceAttribute>
- <destinationAttribute>icalendar</destinationAttribute>
-</mailet>
-<mailet match="All" class="ICALToHeader">
- <attribute>icalendar</attribute>
-</mailet>
-<mailet match="All" class="ICALToJsonAttribute">
- <source>icalendar</source>
- <destination>icalendarAsJson</destination>
- <rawSource>rawIcalendar</rawSource>
-</mailet>
-<mailet match="All" class="AmqpForwardAttribute">
- <uri>amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}</uri>
- <exchange>james:events</exchange>
- <attribute>icalendarAsJson</attribute>
-</mailet>
-<!-- End of ICAL pipeline -->
-....
-
-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 ecc0c80ce3..1954a4b6b3 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 53b9b0f4c4..ad5cbafffe 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 375b6156b7..500aee7a5d 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` :
-
-....
-<mailet match="org.apache.james.transport.matchers.IsInDropList" class="ToProcessor">
- <processor>transport</processor>
-</mailet>
-....
-
-== 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 714324b640..8085aaa0da 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` :
-
-....
-<smtpserver enabled="true">
- <...> <!-- The rest of your SMTP configuration, unchanged -->
- <handlerchain>
- <handler class="org.apache.james.smtpserver.dsn.DSNEhloHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNMailParameterHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNRcptParameterHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNMessageHook"/>
- <...> <!-- other handlers, like: -->
- <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/> <!-- for instance -->
- </handlerchain>
-</smtpserver>
-....
-
-== 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...
-
-....
-<mailetcontainer enableJmx="true">
- <!-- Common processing settings are unchanged -->
-
- <processors>
- <processor state="root" enableJmx="true">\
- <!-- Content of root processor is unchanged -->
- </processor>
-
- <processor state="transport" enableJmx="true">
- <!-- transport processor unchanged -->
- </processor>
-
- <processor state="error" enableJmx="true">
- <mailet match="DSNFailureRequested" class="DSNBounce">
- <prefix>[FAILED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>failed</action>
- <defaultStatus>5.0.0</defaultStatus>
- </mailet>
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/</repositoryPath>
- </mailet>
- </processor>
-
- <processor state="local-delivery" enableJmx="true">
- <!-- Your local-delivery pipeline -->
- <mailet match="All" class="LocalDelivery">
- <!-- Do not abort the pipeline yet -->
- <consume>false</consume>
- </mailet>
- <!-- Tell the world we succeeded -->
- <mailet match="DSNSuccessRequested" class="DSNBounce">
- <prefix>[SUCCESS]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>delivered</action>
- <defaultStatus>2.0.0</defaultStatus>
- </mailet>
- <mailet match="All" class="Null"/> <!-- ignore people not having requesting a dsn success bounce -->
- </processor>
-
- <processor state="relay" enableJmx="true">
- <!-- Perform at most 5 RemoteDelivery attempts -->
- <mailet match="AtMost=5" class="RemoteDelivery">
- <outgoingQueue>outgoing</outgoingQueue>
- <maxRetries>0</maxRetries>
- <maxDnsProblemRetries>0</maxDnsProblemRetries>
- <deliveryThreads>10</deliveryThreads>
- <sendpartial>true</sendpartial>
- <!-- Use a custom processor for error handling -->
- <bounceProcessor>remote-delivery-error</bounceProcessor>
- </mailet>
- <!-- When retries are exceeded, consider the mail as a permanent failure -->
- <mailet match="DSNFailureRequested" class="DSNBounce">
- <prefix>[FAILED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>failed</action>
- <defaultStatus>5.0.0</defaultStatus>
- </mailet>
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
- </mailet>
- </processor>
-
- <processor state="remote-delivery-error" enableJmx="true">
- <matcher name="dsn-permanent" match="org.apache.james.mailetcontainer.impl.matchers.And">
- <matcher match="IsRemoteDeliveryPermanentError"/>
- <matcher match="DSNFailureRequested"/>
- </matcher>
- <matcher name="dsn-temporary" match="org.apache.james.mailetcontainer.impl.matchers.And">
- <matcher match="IsRemoteDeliveryTemporaryError"/>
- <matcher match="DSNDelayRequested"/>
- </matcher>
-
- <mailet match="dsn-permanent" class="DSNBounce">
- <prefix>[FAILED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>failed</action>
- <defaultStatus>5.0.0</defaultStatus>
- </mailet>
-
- <mailet match="dsn-temporary" class="DSNBounce">
- <prefix>[DELAYED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>delayed</action>
- <defaultStatus>4.0.0</defaultStatus>
- </mailet>
-
- <!-- Error management for remote delivery error handling as described in remote-delivery-error-handling.adoc -->
- </processor>
-
- <processor state="local-address-error" enableJmx="true">
- <mailet match="DSNFailureRequested" class="DSNBounce">
- <prefix>[FAILED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>failed</action>
- <defaultStatus>5.0.0</defaultStatus>
- </mailet>
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/address-error/</repositoryPath>
- </mailet>
- </processor>
-
- <processor state="relay-denied" enableJmx="true">
- <!-- This is an abuse, you likely do not want to be polite with these people. we just keep a copy for later audit & replay -->
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/relay-denied/</repositoryPath>
- <notice>Warning: You are sending an e-mail to a remote server. You must be authenticated to perform such an operation</notice>
- </mailet>
- </processor>
-
- <processor state="rrt-error" enableJmx="false">
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/rrt-error/</repositoryPath>
- <passThrough>true</passThrough>
- </mailet>
- <mailet match="IsSenderInRRTLoop" class="Null"/>
- <mailet match="DSNFailureRequested" class="DSNBounce">
- <prefix>[FAILED]</prefix>
- <passThrough>true</passThrough>
- <messageString>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.</messageString>
- <action>failed</action>
- <defaultStatus>5.1.6/defaultStatus>
- </mailet>
- </processor>
- </processors>
-</mailetcontainer>
-....
-
-== 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 876fb5cd84..95f754529c 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<TaskDTOModule<? extends Task, ? extends TaskDTO>> taskDTOModules() {
- return Set.of(...);
- }
-
- @Override
- public Set<AdditionalInformationDTOModule<? extends TaskExecutionDetails.AdditionalInformation, ? extends AdditionalInformationDTO>> taskAdditionalInformationDTOModules() {
- return Set.of(...);
- }
-}
-....
-
-Recording it in extensions.properties :
-
-....
-guice.extension.tasks=com.project.RspamdTaskExtensionModule
-....
-
-Read xref:distributed/extending/index.adoc#_defining_custom_injections_for_your_extensions[this page] for more details.
\ 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/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 37c01f8c81..82a147ea2c 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 0060bcaf5b..79c6a9d93a 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:distributed/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].
+: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 8a99ac9a4d..76c4453c38 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 9d7611ba13..65fb94ab6e 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 04e88db20c..486a90ca72 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.<br/>
-
-James JMX endpoint provides command line utilities and exposes a few metrics, also available on the metric endpoint.</p>
-
-== 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 170869594b..cbb3998dc4 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 57d7772fba..d0cf02d848 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 <executeGroupListeners> 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 <listener>.
-
-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:
-
-....
-<listeners>
- <!-- ... -->
- <listener>
- <class>org.apache.james.mailbox.spamassassin.SpamAssassinListener</class>
- </listener>
-</listeners>
-....
-
-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:
-
-....
-<listeners>
- <!-- ... -->
- <listener>
- <class>org.apache.james.rspamd.RspamdListener</class>
- </listener>
-</listeners>
-....
-
-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]
....
<listeners>
<listener>
@@ -89,85 +22,3 @@ Example:
<!-- ... -->
</listeners>
....
-
-=== 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:
-
-....
-<listeners>
- <!-- ... -->
- <listener>
- <class>org.apache.james.mailbox.quota.mailing.listeners.QuotaThresholdCrossingListener</class>
- <group>QuotaThresholdCrossingListener-upper-threshold</group>
- <configuration>
- <thresholds>
- <threshold>
- <value>0.8</value>
- </threshold>
- </thresholds>
- <name>thirst</name>
- <subjectTemplate>conf://templates/QuotaThresholdMailSubject.mustache</subjectTemplate>
- <bodyTemplate>conf://templates/QuotaThresholdMailBody.mustache</bodyTemplate>
- <gracePeriod>1week/</gracePeriod>
- </configuration>
- </listener>
-</listeners>
-....
-
-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 8bac9254ff..e996c27680 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:distributed/extending/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@<servername>, where <servername> 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:</p>
-
-....
-<mailet match="RemoteAddrNotInNetwork=127.0.0.1" class="ToProcessor">
- <processor>spam</processor>
-</mailet>
-....
-
-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:
-
-....
-<mailet match=RecipientIsLocal class="LocalDelivery">
- <onMailetException>deliveryError</onMailetException>
- <onMatcherException>nomatch</onMatcherException>
-</mailet>
-....
\ 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/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 37e13f4c5b..2426eae065 100644
--- a/docs/modules/servers/pages/distributed/configure/mailets.adoc
+++ b/docs/modules/servers/pages/distributed/configure/mailets.adoc
@@ -1,149 +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$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
+: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 8208c1c948..6968de99ba 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:distributed/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:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/mailrepositorystore.xml[example]
-to get some examples and hints.
-
-....
-<mailrepositorystore>
- <defaultProtocol>cassandra</defaultProtocol>
- <mailrepositories>
- <mailrepository class="org.apache.james.mailrepository.cassandra.CassandraMailRepository">
- <protocols>
- <protocol>cassandra</protocol>
- </protocols>
- </mailrepository>
- </mailrepositories>
-</mailrepositorystore>
-....
-
-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 25cc76ccf7..944b9e46a7 100644
--- a/docs/modules/servers/pages/distributed/configure/matchers.adoc
+++ b/docs/modules/servers/pages/distributed/configure/matchers.adoc
@@ -1,168 +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$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*:
-
-....
-<processor state="transport" enableJmx="true">
- <matcher name="relay-allowed" match="org.apache.james.mailetcontainer.impl.matchers.Or">
- <matcher match="SMTPAuthSuccessful"/>
- <matcher match="SentByMailet"/>
- <matcher match="org.apache.james.jmap.mailet.SentByJmap"/>
- <matcher match="RemoteAddrInNetwork=127.0.0.1, 10.2.*, 193.50.151.*"/>
- </matcher>
-
- <!-- ... -->
-
- <mailet match="relay-allowed" class="ToProcessor">
- <processor>relay</processor>
- </mailet>
-</processor>
-....
\ 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 0b70fd3b43..2144b92850 100644
--- a/docs/modules/servers/pages/distributed/configure/opensearch.adoc
+++ b/docs/modules/servers/pages/distributed/configure/opensearch.adoc
@@ -1,311 +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.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: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 43db960b86..1179dadf07 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 ce2dfe2bff..e9907a090a 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 f0871e0d5d..3f183ed468 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 108e09e56f..983756ca61 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 a67a3a964e..659ca53b35 100644
--- a/docs/modules/servers/pages/distributed/configure/redis.adoc
+++ b/docs/modules/servers/pages/distributed/configure/redis.adoc
@@ -1,31 +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.
-|===
+: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 55764e7a5d..68efbdb38f 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:
-
-....
- <processor state="relay" enableJmx="true">
- <!-- Perform at most 5 RemoteDelivery attemps -->
- <mailet match="AtMost=5" class="RemoteDelivery">
- <outgoingQueue>outgoing</outgoingQueue>
- <maxRetries>0</maxRetries>
- <maxDnsProblemRetries>0</maxDnsProblemRetries>
- <deliveryThreads>10</deliveryThreads>
- <sendpartial>true</sendpartial>
- <!-- Use a custom processor for error handling -->
- <bounceProcessor>remote-delivery-error</bounceProcessor>
- </mailet>
- <!-- When retries are exceeded, consider the mail as a permanent failure -->
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
- </mailet>
- </processor>
-
- <processor state="remote-delivery-error" enableJmx="true">
- <!-- Store temporary failures separately for later retries -->
- <mailet match="IsRemoteDeliveryTemporaryError" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/temporary/</repositoryPath>
- </mailet>
- <!-- Store permanent failures for audit -->
- <mailet match="IsRemoteDeliveryPermanentError" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
- </mailet>
- <!-- Mail getting that far were not processed by remote delivery.
- Likely a configuration error. -->
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/</repositoryPath>
- </mailet>
- </processor>
-....
-
-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 735b843bfa..f4d5b15671 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 3874f3c6c4..b3b3c4f16f 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.</p>
-
-== 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 0cc5ef3c8e..4505123132 100644
--- a/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
+++ b/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
@@ -1,352 +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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.DNSRBLHandler">
- <getDetail>false</getDetail>
- <rblservers>
- <whitelist>query.bondedsender.org.</whitelist>
- <blacklist>sbl-xbl.spamhaus.org.</blacklist>
- <blacklist>dul.dnsbl.sorbs.net.</blacklist>
- <blacklist>list.dsbl.org.</blacklist>
- </rblservers>
- </handler>
-</handlerchain>
-....
-
-== 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].
-
-....
-<smtpserver enabled="true">
- <...> <!-- The rest of your SMTP configuration, unchanged -->
- <handlerchain>
- <handler class="org.apache.james.smtpserver.dsn.DSNEhloHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNMailParameterHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNRcptParameterHook"/>
- <handler class="org.apache.james.smtpserver.dsn.DSNMessageHook"/>
- <...> <!-- other handlers, like: -->
- <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/> <!-- for instance -->
- </handlerchain>
-</smtpserver>
-....
-
-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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.MailPriorityHandler">
- <priorityEntries>
- <priorityEntry>
- <domain>yourdomain1</domain>
- <priority>1</priority>
- </priorityEntry>
- <priorityEntry>
- <domain>yourdomain2</domain>
- <priority>9</priority>
- </priorityEntry>
- <priorityEntries>
- </handler>
-</handlerchain>
-....
-
-== MaxRcptHandler
-If activated you can limit the maximal recipients.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.MaxRcptHandler">
- <maxRcpt>10</maxRcpt>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.POP3BeforeSMTPHandler">
- <expireTime>1 hour</expireTime>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.ResolvableEhloHeloHandler"/>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.ReverseEqualsEhloHeloHandler"/>
-</handlerchain>
-....
-
-== SetMimeHeaderHandler
-
-This handler allows you to add mime headers to the processed mails.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.SetMimeHeaderHandler">
- <headername>SPF-test</headername>
- <headervalue>passed</headervalue>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.SpamAssassinHandler">
- <spamdHost>127.0.0.1</spamdHost>
- <spamdPort>783</spamdPort>
- <spamdRejectionHits>10</spamdRejectionHits>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.SPFHandler">
- <blockSoftFail>false</blockSoftFail>
- <blockPermError>true</blockPermError>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.URIRBLHandler">
- <action>reject</action>
- <getDetail>true</getDetail>
- <uriRblServers>
- <server>multi.surbl.org</server>
- </uriRblServers>
- </handler>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
-</handlerchain>
-....
-
-== 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:
-
-....
-<handlerchain>
- <!-- ... -->
- <handler class="org.apache.james.smtpserver.fastfail.ValidSenderDomainHandler"/>
-</handlerchain>
-....
-
-== FUTURERELEASE hooks
-
-The Distributed server has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])
-
-....
-<smtpserver enabled="true">
- <...> <!-- The rest of your SMTP configuration, unchanged -->
- <handlerchain>
- <handler class="org.apache.james.smtpserver.futurerelease.FutureReleaseEHLOHook"/>
- <handler class="org.apache.james.smtpserver.futurerelease.FutureReleaseMailParameterHook"/>
- <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
- </handlerchain>
-</smtpserver>
-....
-
-== 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`:
-
-....xml
-<handlerchain>
-<handler class="org.apache.james.smtpserver.DKIMHook">
-<forceCLRF>true</forceCLRF>
-<onlyForSenderDomain>apache.org</onlyForSenderDomain>
-<signatureRequired>true</signatureRequired>
-<expectedDToken>apache.org</expectedDToken>
-</handler>
-<handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
-</handlerchain>
-....
-
-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 34e2288714..85f0845c48 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:
-
-....
-<lmtpservers>
- <lmtpserver enabled="true">
- <jmxName>lmtpserver</jmxName>
- <bind>0.0.0.0:24</bind>
- <connectionBacklog>200</connectionBacklog>
- <connectiontimeout>1200</connectiontimeout>
- <connectionLimit>0</connectionLimit>
- <connectionLimitPerIP>0</connectionLimitPerIP>
- <maxmessagesize>0</maxmessagesize>
- <handlerchain coreHandlersPackage="org.apache.james.lmtpserver.MailetContainerCmdHandlerLoader">
- <handler class="org.apache.james.lmtpserver.MailetContainerCmdHandlerLoader"/>
- </handlerchain>
- </lmtpserver>
-</lmtpservers>
-....
-
-Note that by default the mailet container is executed with all recipients at once and do not allow per recipient
-error reporting. An option <code>splitExecution</code> allow to execute the mailet container for each recipient separately and mitigate this
-limitation at the cost of performance.
-
-....
-<lmtpservers>
- <lmtpserver enabled="true">
- <jmxName>lmtpserver</jmxName>
- <bind>0.0.0.0:24</bind>
- <connectionBacklog>200</connectionBacklog>
- <connectiontimeout>1200</connectiontimeout>
- <connectionLimit>0</connectionLimit>
- <connectionLimitPerIP>0</connectionLimitPerIP>
- <maxmessagesize>0</maxmessagesize>
- <handlerchain coreHandlersPackage="org.apache.james.lmtpserver.MailetContainerCmdHandlerLoader">
- <handler class="org.apache.james.lmtpserver.MailetContainerCmdHandlerLoader"/>
- <handler class="org.apache.james.lmtpserver.MailetContainerHandler">
- <splitExecution>true</splitExecution>
- </handler>
- </handlerchain>
- </lmtpserver>
-</lmtpservers>
-....
\ 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 8a7839d604..4b7dabd797 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:
-
-....
-<processor state="local-delivery" enableJmx="true">
- <mailet match="All" class="org.apache.james.rspamd.RspamdScanner">
- <rewriteSubject>true</rewriteSubject>
- <virusProcessor>virus</virusProcessor>
- <rejectSpamProcessor>spam</rejectSpamProcessor>
- </mailet>
- <mailet match="IsMarkedAsSpam=org.apache.james.rspamd.status" class="WithStorageDirective">
- <targetFolderName>Spam</targetFolderName>
- </mailet>
- <mailet match="All" class="LocalDelivery"/>
-</processor>
-<!--Choose one between these two following virus processor, or configure a custom one if you want-->
-<!--Hard reject virus mail-->
-<processor state="virus" enableJmx="false">
- <mailet match="All" class="ToRepository">
- <repositoryPath>file://var/mail/virus/</repositoryPath>
- </mailet>
-</processor>
-<!--Soft reject virus mail-->
-<processor state="virus" enableJmx="false">
- <mailet match="All" class="StripAttachment">
- <remove>all</remove>
- <pattern>.*</pattern>
- </mailet>
- <mailet match="All" class="AddSubjectPrefix">
- <subjectPrefix>[VIRUS]</subjectPrefix>
- </mailet>
- <mailet match="All" class="LocalDelivery"/>
-</processor>
-<!--Store rejected spam emails (with a very high score) -->
-<processor state="virus" enableJmx="false">
- <mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/spam</repositoryPath>
- </mailet>
-</processor>
-....
-
-==== 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:
-
-....
-<listeners>
- <listener>
- <class>org.apache.james.rspamd.RspamdListener</class>
- </listener>
-</listeners>
-....
-
-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:
-
-....
-<mailet match="All" class="SpamAssassin">
- <onMailetException>ignore</onMailetException>
- <spamdHost>spamassassin</spamdHost>
- <spamdPort>783</spamdPort>
-</mailet>
-<mailet match="All" class="MailAttributesToMimeHeaders">
- <!-- This mailet is not required, but useful to have SpamAssassin score in headers-->
- <simplemapping>org.apache.james.spamassassin.status; X-JAMES-SPAMASSASSIN-STATUS</simplemapping>
- <simplemapping>org.apache.james.spamassassin.flag; X-JAMES-SPAMASSASSIN-FLAG</simplemapping>
-</mailet>
-<mailet match="IsMarkedAsSpam" class="WithStorageDirective">
- <targetFolderName>Spam</targetFolderName>
-</mailet>
-....
-
-* *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:
-
-....
-<listeners>
- <listener>
- <class>org.apache.james.mailbox.spamassassin.SpamAssassinListener</class>
- <async>true</async>
- </listener>
-</listeners>
-....
+: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 b21a17fa3a..f77590ec95 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,..)
-
-....
-<tls socketTLS="false" startTLS="true">
- <keystore>file://conf/keystore</keystore>
- <keystoreType>PKCS12</keystoreType>
- <secret>yoursecret</secret>
- <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider>
-</tls>
-....
-
-Alternatively TLS keys can be supplied via PEM files:
-
-....
-<tls socketTLS="true" startTLS="false">
- <privateKey>file://conf/private.key</privateKey>
- <certificates>file://conf/certs.self-signed.csr</certificates>
-</tls>
-....
-
-An optional secret might be specified for the private key:
-
-....
-<tls socketTLS="true" startTLS="false">
- <privateKey>file://conf/private.key</privateKey>
- <certificates>file://conf/certs.self-signed.csr</certificates>
- <secret>yoursecret</secret>
-</tls>
-....
-
-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:
-....
-<tls socketTLS="true" startTLS="false">
- <supportedProtocols>
- <protocol>TLSv1.2</protocol>
- <protocol>TLSv1.1</protocol>
- <protocol>TLSv1</protocol>
- <protocol>SSLv3</protocol>
- </supportedProtocols>
- <supportedCipherSuites>
- <cipherSuite>TLS_AES_256_GCM_SHA384</cipherSuite>
- <cipherSuite>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</cipherSuite>
- </supportedCipherSuites>
-</tls>
-....
-
-Each of these block has an optional boolean configuration element <b>socketTLS</b> and <b>startTLS</b> 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):
-
-....
-<tls socketTLS="false" startTLS="true">
- <keystore>file://conf/keystore</keystore>
- <keystoreType>JKS</keystoreType>
- <secret>yoursecret</secret>
- <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider>
-</tls>
-....
-
-
-=== Client authentication via certificates
-
-When you enable TLS, you may also configure the server to require a client certificate for authentication:
-
-....
-<tls socketTLS="false" startTLS="true">
- <keystore>file://conf/keystore</keystore>
- <keystoreType>JKS</keystoreType>
- <secret>yoursecret</secret>
-
- <clientAuth>
- <truststore>file://conf/truststore</truststore>
- <truststoreType>JKS</truststoreType>
- <truststoreSecret>yoursecret</truststoreSecret>
- <enableOCSPCRLChecks>false</enableOCSPCRLChecks>
- </clientAuth>
-</tls>
-....
-
-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:
-
-....
-<tls socketTLS="true" startTLS="false">
- <privateKey>file://conf/private.nopass.key</privateKey>
- <certificates>file://conf/certs.self-signed.csr</certificates>
-</tls>
-....
-
-== 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 fdb2cc9cf7..604b31e486 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 08f8f674ed..d4cef0a23f 100644
--- a/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
+++ b/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
@@ -1,124 +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:
-
-....
-<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
- principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid">
- <enableVirtualHosting>true</enableVirtualHosting>
-</usersrepository>
-....
-
-SSL can be enabled by using `ldaps` scheme. `trustAllCerts` option can be used to trust all LDAP client certificates
-(optional, defaults to false).
-
-Example:
-
-....
-<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldaps://myldapserver:636"
- principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
- trustAllCerts="true">
- <enableVirtualHosting>true</enableVirtualHosting>
-</usersrepository>
-....
-
-Moreover, per domain base DN can be configured:
-
-....
-<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
- principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
- <enableVirtualHosting>true</enableVirtualHosting>
- <domains>
- <domain.tld>ou=People,o=other.com,ou=system</domain.tld>
- </domains>
-</usersrepository>
-....
-
-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:
-
-....
-<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636"
- principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid" trustAllCerts="true">
- <enableVirtualHosting>true</enableVirtualHosting>
-</usersrepository>
-....
-
-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:
-
-....
-<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636"
- principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" resolveLocalPartAttribute="uid" userIdAttribute="mail" trustAllCerts="true">
- <enableVirtualHosting>true</enableVirtualHosting>
-</usersrepository>
-....
-
-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.
+: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 b65a4c347d..97ee4a3247 100644
--- a/docs/modules/servers/pages/distributed/configure/vault.adoc
+++ b/docs/modules/servers/pages/distributed/configure/vault.adoc
@@ -1,32 +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
-
-| 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 01477845c3..13393213f9 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:distributed/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 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.
\ 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/webadmin.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/batchsizes.adoc b/docs/modules/servers/partials/configure/batchsizes.adoc
similarity index 80%
copy from docs/modules/servers/pages/distributed/configure/batchsizes.adoc
copy to docs/modules/servers/partials/configure/batchsizes.adoc
index 4d6123e468..6e123c9f90 100644
--- a/docs/modules/servers/pages/distributed/configure/batchsizes.adoc
+++ b/docs/modules/servers/partials/configure/batchsizes.adoc
@@ -1,12 +1,9 @@
-= 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]
+Consult this link:{sample-configuration-prefix-url}/batchsizes.properties[example]
to get some examples and hints.
.batchsizes.properties content
diff --git a/docs/modules/servers/pages/distributed/configure/blobstore.adoc b/docs/modules/servers/partials/configure/blobstore.adoc
similarity index 63%
copy from docs/modules/servers/pages/distributed/configure/blobstore.adoc
copy to docs/modules/servers/partials/configure/blobstore.adoc
index 0ebcf516d5..e928386bbb 100644
--- a/docs/modules/servers/pages/distributed/configure/blobstore.adoc
+++ b/docs/modules/servers/partials/configure/blobstore.adoc
@@ -1,56 +1,3 @@
-= Distributed James Server — blobstore.properties
-:navtitle: blobstore.properties
-
-== BlobStore
-
-This file is optional. If omitted, the *cassandra* blob store will be used.
-
-BlobStore is the dedicated component to store blobs, non-indexable content.
-James uses the BlobStore for storing blobs which are usually mail contents, attachments, deleted mails...
-
-You can choose the underlying implementation of BlobStore to fit with your James setup.
-
-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]
-in GIT to get some examples and hints.
-
-=== Implementation choice
-
-*implementation* :
-
-* 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.
-
-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)
-
-The generated startup warning log can be deactivated via the `cassandra.blob.store.disable.startup.warning` environment
-variable being positioned to `false`.
-
-*deduplication.enable*: Mandatory. Supported value: true and false.
-
-If you choose to enable deduplication, the mails with the same content will be stored only once.
-
-WARNING: Once this feature is enabled, there is no turning back as turning it off will lead to the deletion of all
-the mails sharing the same content once one is deleted.
-
-NOTE: If you are upgrading from James 3.5 or older, the deduplication was enabled.
-
-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].
-
-In order to avoid concurrency issues upon garbage collection, we slice the blobs in generation, the two more recent
-generations are not garbage collected.
-
-*deduplication.gc.generation.duration*: Allow controlling the duration of one generation. Longer implies better deduplication
-but deleted blobs will live longer. Duration, defaults on 30 days, the default unit is in days.
-
-*deduplication.gc.generation.family*: Every time the duration is changed, this integer counter must be incremented to avoid
-conflicts. Defaults to 1.
=== Encryption choice
@@ -100,30 +47,6 @@ james.blob.aes.file.threshold.decrypt=256K
james.blob.aes.blob.max.size=100M
....
-=== Cassandra BlobStore Cache
-
-A Cassandra cache can be enabled to reduce latency when reading small blobs frequently.
-A dedicated keyspace with a replication factor of one is then used.
-Cache eviction policy is TTL based.
-Only blobs below a given threshold will be stored.
-To be noted that blobs are stored within a single Cassandra row, hence a low threshold should be used.
-
-.blobstore.properties cache related content
-|===
-| Property name | explanation
-
-| cache.enable
-| DEFAULT: false, optional, must be a boolean. Whether the cache should be enabled.
-
-| cache.cassandra.ttl
-| DEFAULT: 7 days, optional, must be a duration. Cache eviction policy is TTL based.
-
-| cache.sizeThresholdInBytes
-| DEFAULT: 8192, optional, must be a positive integer. Unit: bytes.
-Supported units: bytes, Kib, MiB, GiB, TiB
-Maximum size of stored objects expressed in bytes.
-|===
-
=== Object storage configuration
==== AWS S3 Configuration
@@ -211,7 +134,7 @@ The deleted messages are transformed into a blob and James will export that blob
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]
+Consult {sample-configuration-prefix-url}/blob.properties[blob.properties]
in GIT to get some examples and hints.
Configuration for exporting blob content:
@@ -243,7 +166,7 @@ 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]
+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
diff --git a/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc b/docs/modules/servers/partials/configure/collecting-contacts.adoc
similarity index 97%
copy from docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc
copy to docs/modules/servers/partials/configure/collecting-contacts.adoc
index ed00b04d24..ed10312455 100644
--- a/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc
+++ b/docs/modules/servers/partials/configure/collecting-contacts.adoc
@@ -1,5 +1,3 @@
-= Contact collection
-
== Motivation
Many modern applications combines email and contacts.
@@ -17,6 +15,7 @@ We can achieve this goal by combining simple mailets building blocks.
Here is a sample pipeline achieving aforementioned objectives :
+[source,xml]
....
<mailet match="SenderIsLocal" class="ContactExtractor">
<attribute>extractedContacts</attribute>
diff --git a/docs/modules/servers/pages/distributed/configure/collecting-events.adoc b/docs/modules/servers/partials/configure/collecting-events.adoc
similarity index 99%
copy from docs/modules/servers/pages/distributed/configure/collecting-events.adoc
copy to docs/modules/servers/partials/configure/collecting-events.adoc
index f103a76a23..4a3ee1f87d 100644
--- a/docs/modules/servers/pages/distributed/configure/collecting-events.adoc
+++ b/docs/modules/servers/partials/configure/collecting-events.adoc
@@ -1,5 +1,3 @@
-= Event collection
-
== Motivation
Many calendar application do add events invitation received by email directly in ones calendar.
@@ -17,6 +15,7 @@ We can achieve this goal by combining simple mailets building blocks.
Here is a sample pipeline achieving aforementioned objectives :
+[source,xml]
....
<!-- ICAL pipeline -->
<mailet match="All" class="StripAttachment">
diff --git a/docs/modules/servers/pages/distributed/configure/dns.adoc b/docs/modules/servers/partials/configure/dns.adoc
similarity index 91%
copy from docs/modules/servers/pages/distributed/configure/dns.adoc
copy to docs/modules/servers/partials/configure/dns.adoc
index ecc0c80ce3..e61491f20e 100644
--- a/docs/modules/servers/pages/distributed/configure/dns.adoc
+++ b/docs/modules/servers/partials/configure/dns.adoc
@@ -1,7 +1,4 @@
-= 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]
+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.
diff --git a/docs/modules/servers/pages/distributed/configure/domainlist.adoc b/docs/modules/servers/partials/configure/domainlist.adoc
similarity index 89%
copy from docs/modules/servers/pages/distributed/configure/domainlist.adoc
copy to docs/modules/servers/partials/configure/domainlist.adoc
index 53b9b0f4c4..bd693f7094 100644
--- a/docs/modules/servers/pages/distributed/configure/domainlist.adoc
+++ b/docs/modules/servers/partials/configure/domainlist.adoc
@@ -1,7 +1,4 @@
-= 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]
+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.
diff --git a/docs/modules/servers/pages/distributed/configure/droplists.adoc b/docs/modules/servers/partials/configure/droplists.adoc
similarity index 85%
copy from docs/modules/servers/pages/distributed/configure/droplists.adoc
copy to docs/modules/servers/partials/configure/droplists.adoc
index 375b6156b7..f08ae18a9b 100644
--- a/docs/modules/servers/pages/distributed/configure/droplists.adoc
+++ b/docs/modules/servers/partials/configure/droplists.adoc
@@ -1,6 +1,3 @@
-= 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.
@@ -19,6 +16,7 @@ To disable it, adjust the `droplists.properties` file and remove the `IsInDropLi
Plug the `IsInDropList` matcher within `mailetcontainer.xml` :
+[source,xml]
....
<mailet match="org.apache.james.transport.matchers.IsInDropList" class="ToProcessor">
<processor>transport</processor>
@@ -29,4 +27,4 @@ Plug the `IsInDropList` matcher within `mailetcontainer.xml` :
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
+See xref:{pages-path}/operate/webadmin.adoc#_administrating_droplists[WebAdmin DropLists].
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/dsn.adoc b/docs/modules/servers/partials/configure/dsn.adoc
similarity index 89%
copy from docs/modules/servers/pages/distributed/configure/dsn.adoc
copy to docs/modules/servers/partials/configure/dsn.adoc
index 714324b640..9ff0cfb3f7 100644
--- a/docs/modules/servers/pages/distributed/configure/dsn.adoc
+++ b/docs/modules/servers/partials/configure/dsn.adoc
@@ -1,22 +1,20 @@
-= 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.
+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:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] to generate DSN bounces when needed
+- 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]
....
<smtpserver enabled="true">
<...> <!-- The rest of your SMTP configuration, unchanged -->
@@ -34,10 +32,10 @@ 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.
+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:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] achieving the following DSN generation:
+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
@@ -47,7 +45,8 @@ Here is a sample xref:distributed/configure/mailetcontainer.adoc[mailetcontainer
- 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]
+----
<mailetcontainer enableJmx="true">
<!-- Common processing settings are unchanged -->
@@ -73,7 +72,7 @@ your message.</messageString>
<defaultStatus>5.0.0</defaultStatus>
</mailet>
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/</repositoryPath>
</mailet>
</processor>
@@ -122,7 +121,7 @@ your message.</messageString>
<defaultStatus>5.0.0</defaultStatus>
</mailet>
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/</repositoryPath>
</mailet>
</processor>
@@ -176,21 +175,21 @@ The following addresses do not exist here. Sorry.</messageString>
<defaultStatus>5.0.0</defaultStatus>
</mailet>
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/address-error/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/address-error/</repositoryPath>
</mailet>
</processor>
<processor state="relay-denied" enableJmx="true">
<!-- This is an abuse, you likely do not want to be polite with these people. we just keep a copy for later audit & replay -->
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/relay-denied/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/relay-denied/</repositoryPath>
<notice>Warning: You are sending an e-mail to a remote server. You must be authenticated to perform such an operation</notice>
</mailet>
</processor>
<processor state="rrt-error" enableJmx="false">
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/rrt-error/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/rrt-error/</repositoryPath>
<passThrough>true</passThrough>
</mailet>
<mailet match="IsSenderInRRTLoop" class="Null"/>
@@ -205,12 +204,12 @@ 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.</messageString>
<action>failed</action>
- <defaultStatus>5.1.6/defaultStatus>
+ <defaultStatus>5.1.6</defaultStatus>
</mailet>
</processor>
</processors>
</mailetcontainer>
-....
+----
== Limitations
diff --git a/docs/modules/servers/pages/distributed/configure/extensions.adoc b/docs/modules/servers/partials/configure/extensions.adoc
similarity index 88%
copy from docs/modules/servers/pages/distributed/configure/extensions.adoc
copy to docs/modules/servers/partials/configure/extensions.adoc
index 876fb5cd84..6c2ae7cbaa 100644
--- a/docs/modules/servers/pages/distributed/configure/extensions.adoc
+++ b/docs/modules/servers/partials/configure/extensions.adoc
@@ -1,12 +1,10 @@
-= 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 :
+[source,java]
....
public class MyServiceModule extends AbstractModule {
@Override
@@ -33,6 +31,7 @@ These extensions need to implement Task extension modules.
Here is an example of such a class :
+[source,java]
....
public class RspamdTaskExtensionModule implements TaskExtensionModule {
@@ -58,4 +57,4 @@ Recording it in extensions.properties :
guice.extension.tasks=com.project.RspamdTaskExtensionModule
....
-Read xref:distributed/extending/index.adoc#_defining_custom_injections_for_your_extensions[this page] for more details.
\ No newline at end of file
+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 0000000000..2ea8a96102
--- /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 0000000000..49720b5043
--- /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 0000000000..0999218482
--- /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 0000000000..2d498aeda1
--- /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/pages/distributed/configure/healthcheck.adoc b/docs/modules/servers/partials/configure/healthcheck.adoc
similarity index 77%
copy from docs/modules/servers/pages/distributed/configure/healthcheck.adoc
copy to docs/modules/servers/partials/configure/healthcheck.adoc
index 37c01f8c81..afcb1098a8 100644
--- a/docs/modules/servers/pages/distributed/configure/healthcheck.adoc
+++ b/docs/modules/servers/partials/configure/healthcheck.adoc
@@ -1,7 +1,4 @@
-= 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]
+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.
diff --git a/docs/modules/servers/pages/distributed/configure/imap.adoc b/docs/modules/servers/partials/configure/imap.adoc
similarity index 96%
copy from docs/modules/servers/pages/distributed/configure/imap.adoc
copy to docs/modules/servers/partials/configure/imap.adoc
index 0060bcaf5b..05decc7220 100644
--- a/docs/modules/servers/pages/distributed/configure/imap.adoc
+++ b/docs/modules/servers/partials/configure/imap.adoc
@@ -1,7 +1,4 @@
-= 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]
+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.
@@ -156,7 +153,7 @@ It uses the Keycloak OIDC provider, but usage of similar technologies is definit
== Extending IMAP
-IMAP decoders, processors and encoder can be customized. xref:distributed/extending/imap.adoc[Read more].
+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].
diff --git a/docs/modules/servers/pages/distributed/configure/jmap.adoc b/docs/modules/servers/partials/configure/jmap.adoc
similarity index 95%
copy from docs/modules/servers/pages/distributed/configure/jmap.adoc
copy to docs/modules/servers/partials/configure/jmap.adoc
index 9d7611ba13..5dbfd83507 100644
--- a/docs/modules/servers/pages/distributed/configure/jmap.adoc
+++ b/docs/modules/servers/partials/configure/jmap.adoc
@@ -1,11 +1,8 @@
-= 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]
+Consult this link:{sample-configuration-prefix-url}/jmap.properties[example]
to get some examples and hints.
.jmap.properties content
@@ -56,7 +53,7 @@ Default value: 30M. Supported units are B (bytes) K (KB) M (MB) G (GB).
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?
+| 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
@@ -125,7 +122,7 @@ supported in such a setup, and the `sub` claim is used to identify the user. The
This requires the `JWTAuthenticationStrategy` authentication strategy to be used.
-The Distributed server enforces the use of RSA-SHA-256.
+The {server-name} enforces the use of RSA-SHA-256.
One can use OpenSSL to generate a JWT key pair :
diff --git a/docs/modules/servers/pages/distributed/configure/jmx.adoc b/docs/modules/servers/partials/configure/jmx.adoc
similarity index 90%
copy from docs/modules/servers/pages/distributed/configure/jmx.adoc
copy to docs/modules/servers/partials/configure/jmx.adoc
index 04e88db20c..706bd52298 100644
--- a/docs/modules/servers/pages/distributed/configure/jmx.adoc
+++ b/docs/modules/servers/partials/configure/jmx.adoc
@@ -1,6 +1,3 @@
-= Distributed James Server — jmx.properties
-:navtitle: jmx.properties
-
== Disclaimer
JMX poses several security concerns and had been leveraged to conduct arbitrary code execution.
@@ -13,7 +10,7 @@ James JMX endpoint provides command line utilities and exposes a few metrics, al
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]
+Consult this link:{sample-configuration-prefix-url}/jmx.properties[example]
in GIT to get some examples and hints.
.jmx.properties content
diff --git a/docs/modules/servers/pages/distributed/configure/jvm.adoc b/docs/modules/servers/partials/configure/jvm.adoc
similarity index 97%
copy from docs/modules/servers/pages/distributed/configure/jvm.adoc
copy to docs/modules/servers/partials/configure/jvm.adoc
index 170869594b..08e5981264 100644
--- a/docs/modules/servers/pages/distributed/configure/jvm.adoc
+++ b/docs/modules/servers/partials/configure/jvm.adoc
@@ -1,6 +1,3 @@
-= 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,
diff --git a/docs/modules/servers/pages/distributed/configure/listeners.adoc b/docs/modules/servers/partials/configure/listeners.adoc
similarity index 83%
copy from docs/modules/servers/pages/distributed/configure/listeners.adoc
copy to docs/modules/servers/partials/configure/listeners.adoc
index 57d7772fba..4b8acb6670 100644
--- a/docs/modules/servers/pages/distributed/configure/listeners.adoc
+++ b/docs/modules/servers/partials/configure/listeners.adoc
@@ -1,7 +1,4 @@
-= Distributed James Server — listeners.xml
-:navtitle: listeners.xml
-
-Distributed James relies on an event bus system to enrich mailbox capabilities. Each
+{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.
@@ -10,9 +7,9 @@ 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.
+{server-name} 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]
+Consult this link:{sample-configuration-prefix-url}/listener.xml[example]
to get some examples and hints.
== Configuration
@@ -40,6 +37,7 @@ This MailboxListener is supported.
Example:
+[source,xml]
....
<listeners>
<!-- ... -->
@@ -50,7 +48,7 @@ Example:
....
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.
+xref:{pages-path}/configure/spam.adoc[this page] for extra configuration required to support this feature.
=== RspamdListener
@@ -60,6 +58,7 @@ This MailboxListener is supported.
Example:
+[source,xml]
....
<listeners>
<!-- ... -->
@@ -70,25 +69,8 @@ Example:
....
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.
-
-
-=== MailboxOperationLoggingListener
-
-Provides more insights on mailbox operationsby logging them.
-
-This MailboxListener is supported.
-
-Example:
+xref:{pages-path}/configure/spam.adoc[this page] for extra configuration required to support this feature.
-....
-<listeners>
- <listener>
- <class>org.apache.james.mailbox.cassandra.MailboxOperationLoggingListener</class>
- </listener>
- <!-- ... -->
-</listeners>
-....
=== QuotaThresholdCrossingListener
@@ -121,6 +103,7 @@ Configuring several thresholds is supported.
Example:
+[source,xml]
....
<listeners>
<!-- ... -->
diff --git a/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc b/docs/modules/servers/partials/configure/mailetcontainer.adoc
similarity index 86%
copy from docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc
copy to docs/modules/servers/partials/configure/mailetcontainer.adoc
index 8bac9254ff..a3e7c56e29 100644
--- a/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc
+++ b/docs/modules/servers/partials/configure/mailetcontainer.adoc
@@ -1,18 +1,15 @@
-= 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].
+xref:{pages-path}/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].
+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:distributed/extending/mail-processing.adoc[your own mailet and matchers].
+Furthermore, you can write and use with James xref:{pages-path}/extending/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]
+Consult this link:{sample-configuration-prefix-url}/mailetcontainer.xml[example]
to get some examples and hints.
.mailetcontainer.xml content
@@ -44,6 +41,7 @@ instead.
Consider the following simple *mailet* tag:</p>
+[source,xml]
....
<mailet match="RemoteAddrNotInNetwork=127.0.0.1" class="ToProcessor">
<processor>spam</processor>
@@ -88,6 +86,7 @@ special value also allows you to match no recipients when there is an error.
Here is a short example to illustrate this:
+[source,xml]
....
<mailet match=RecipientIsLocal class="LocalDelivery">
<onMailetException>deliveryError</onMailetException>
diff --git a/docs/modules/servers/pages/distributed/configure/mailets.adoc b/docs/modules/servers/partials/configure/mailets.adoc
similarity index 93%
copy from docs/modules/servers/pages/distributed/configure/mailets.adoc
copy to docs/modules/servers/partials/configure/mailets.adoc
index 37e13f4c5b..5c20ff872a 100644
--- a/docs/modules/servers/pages/distributed/configure/mailets.adoc
+++ b/docs/modules/servers/partials/configure/mailets.adoc
@@ -1,8 +1,5 @@
-= 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.
+{server-name} MailetContainer in order to write your own mail processing logic with out-of-the-box components.
== Supported mailets
diff --git a/docs/modules/servers/partials/configure/mailrepositorystore.adoc b/docs/modules/servers/partials/configure/mailrepositorystore.adoc
new file mode 100644
index 0000000000..e0c7b88bc2
--- /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]
+----
+<mailrepositorystore>
+ <defaultProtocol>{mail-repository-protocol}</defaultProtocol>
+ <mailrepositories>
+ <mailrepository class="{mail-repository-class}">
+ <protocols>
+ <protocol>{mail-repository-protocol}</protocol>
+ </protocols>
+ </mailrepository>
+ </mailrepositories>
+</mailrepositorystore>
+----
+
+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/pages/distributed/configure/matchers.adoc b/docs/modules/servers/partials/configure/matchers.adoc
similarity index 95%
copy from docs/modules/servers/pages/distributed/configure/matchers.adoc
copy to docs/modules/servers/partials/configure/matchers.adoc
index 25cc76ccf7..a7e7526a51 100644
--- a/docs/modules/servers/pages/distributed/configure/matchers.adoc
+++ b/docs/modules/servers/partials/configure/matchers.adoc
@@ -1,8 +1,5 @@
-= 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.
+{server-name} MailetContainer in order to write your own mail processing logic with out-of-the-box components.
== Supported matchers
@@ -150,6 +147,7 @@ then the result does not include that recipient.
Here is the syntax to adopt in *mailetcontainer.xml*:
+[source,xml]
....
<processor state="transport" enableJmx="true">
<matcher name="relay-allowed" match="org.apache.james.mailetcontainer.impl.matchers.Or">
diff --git a/docs/modules/servers/pages/distributed/configure/opensearch.adoc b/docs/modules/servers/partials/configure/opensearch.adoc
similarity index 84%
copy from docs/modules/servers/pages/distributed/configure/opensearch.adoc
copy to docs/modules/servers/partials/configure/opensearch.adoc
index 0b70fd3b43..14b1a929b9 100644
--- a/docs/modules/servers/pages/distributed/configure/opensearch.adoc
+++ b/docs/modules/servers/partials/configure/opensearch.adoc
@@ -1,7 +1,34 @@
-= Distributed James Server — opensearch.properties
-:navtitle: opensearch.properties
+== 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:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/opensearch.properties[example]
+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].
@@ -47,7 +74,7 @@ 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
+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.
@@ -130,7 +157,7 @@ This is controlled in the `search.properties` file via the `implementation` prop
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.
+xref:{pages-path}/operate/webadmin.adoc#_reindexing_all_mails[a full re-indexing]needs to be carried out when enabling OpenSearch.
== SSL Trusting Configuration
@@ -195,34 +222,6 @@ 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.
diff --git a/docs/modules/servers/pages/distributed/configure/pop3.adoc b/docs/modules/servers/partials/configure/pop3.adoc
similarity index 90%
copy from docs/modules/servers/pages/distributed/configure/pop3.adoc
copy to docs/modules/servers/partials/configure/pop3.adoc
index 43db960b86..dc01589791 100644
--- a/docs/modules/servers/pages/distributed/configure/pop3.adoc
+++ b/docs/modules/servers/partials/configure/pop3.adoc
@@ -1,7 +1,4 @@
-= 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]
+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.
@@ -35,7 +32,7 @@ port 110 is the well-known/IANA registered port for Standard POP3
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.
+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
diff --git a/docs/modules/servers/pages/distributed/configure/queue.adoc b/docs/modules/servers/partials/configure/queue.adoc
similarity index 87%
copy from docs/modules/servers/pages/distributed/configure/queue.adoc
copy to docs/modules/servers/partials/configure/queue.adoc
index ce2dfe2bff..cbec12d725 100644
--- a/docs/modules/servers/pages/distributed/configure/queue.adoc
+++ b/docs/modules/servers/partials/configure/queue.adoc
@@ -1,6 +1,3 @@
-= Distributed James Server — queue.properties
-:navtitle: queue.properties
-
This configuration helps you configure mail queue you want to select.
== Queue Configuration
diff --git a/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc b/docs/modules/servers/partials/configure/rabbitmq.adoc
similarity index 69%
copy from docs/modules/servers/pages/distributed/configure/rabbitmq.adoc
copy to docs/modules/servers/partials/configure/rabbitmq.adoc
index f0871e0d5d..689bb17a57 100644
--- a/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc
+++ b/docs/modules/servers/partials/configure/rabbitmq.adoc
@@ -1,9 +1,6 @@
-= 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]
+Consult this link:{sample-configuration-prefix-url}/rabbitmq.properties[example]
to get some examples and hints.
== RabbitMQ Configuration
@@ -133,55 +130,6 @@ See link:https://www.rabbitmq.com/docs/quorum-queues#performance-tuning[this sec
raft.segment_max_entries = 32768
....
-== RabbitMQ MailQueue Configuration
-
-James mail queue is a component acting like a queue where it can enqueue and dequeue mails.
-Beside of the basic features, it also allows some extra operations like getting size, browsing all items in the mail queue...
-One of the mailqueue implementation is using RabbitMQ.
-As RabbitMQ doesn't offer enough features to implement efficiently all mailqueue operations,
-this implementation relies on Cassandra.
-
-.rabbitmq.properties content
-|===
-| Property name | explanation
-
-| cassandra.view.enabled
-| Whether the Cassandra administrative view should be activated. Boolean value defaulting to true.
-Not necessarily needed for MDA deployments, mail queue management adds significant complexity.
-
-
-| 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]
-
-| 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]
-
-| 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]
-
-| mailqueue.size.metricsEnabled
-| By default, the metrics are disabled for the mail queue size.
-As computing the size of the mail queue is currently implemented on top of browse operation and thus has a linear complexity,
-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]
-
-| notification.queue.ttl
-| Configure queue ttl (in ms). References: https://www.rabbitmq.com/ttl.html#queue-ttl.
-This is used only on queues used to share notification patterns, are exclusive to a node. If omitted, it will not add the TTL configure when declaring queues.
-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,
diff --git a/docs/modules/servers/partials/configure/recipientrewritetable.adoc b/docs/modules/servers/partials/configure/recipientrewritetable.adoc
new file mode 100644
index 0000000000..67edfe32ad
--- /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/pages/distributed/configure/redis.adoc b/docs/modules/servers/partials/configure/redis.adoc
similarity index 93%
copy from docs/modules/servers/pages/distributed/configure/redis.adoc
copy to docs/modules/servers/partials/configure/redis.adoc
index a67a3a964e..183e335b67 100644
--- a/docs/modules/servers/pages/distributed/configure/redis.adoc
+++ b/docs/modules/servers/partials/configure/redis.adoc
@@ -1,6 +1,3 @@
-= 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]
diff --git a/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
similarity index 72%
copy from docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc
copy to docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
index 55764e7a5d..25d7c121bc 100644
--- a/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc
+++ b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
@@ -1,7 +1,4 @@
-= 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
+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
@@ -49,7 +46,8 @@ Also note that external triggering of the retry process is needed.
Here is an example of configuration achieving the proposed solution:
-....
+[subs=attributes+,xml]
+----
<processor state="relay" enableJmx="true">
<!-- Perform at most 5 RemoteDelivery attemps -->
<mailet match="AtMost=5" class="RemoteDelivery">
@@ -63,26 +61,26 @@ Here is an example of configuration achieving the proposed solution:
</mailet>
<!-- When retries are exceeded, consider the mail as a permanent failure -->
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/</repositoryPath>
</mailet>
</processor>
<processor state="remote-delivery-error" enableJmx="true">
<!-- Store temporary failures separately for later retries -->
<mailet match="IsRemoteDeliveryTemporaryError" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/temporary/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/remote-delivery/temporary/</repositoryPath>
</mailet>
<!-- Store permanent failures for audit -->
<mailet match="IsRemoteDeliveryPermanentError" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/remote-delivery/permanent/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/</repositoryPath>
</mailet>
<!-- Mail getting that far were not processed by remote delivery.
Likely a configuration error. -->
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/error/</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/error/</repositoryPath>
</mailet>
</processor>
-....
+----
Note:
@@ -90,28 +88,30 @@ Note:
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/`.
+- 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 *cassandra://var/mail/error/remote-delivery/temporary/* mailRepository into the *relay* processor.
+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 :
-....
-curl -XPATCH 'http://ip:8000/mailRepositories/cassandra%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails?action=reprocess&processor=relay'
-....
+[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:distributed/operate/webadmin.adoc#_reprocessing_mails_from_a_mail_repository[the documentation].
+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 *cassandra://var/mail/error/remote-delivery/permanent/*. This can be done
+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:
-....
-curl -XGET 'http://ip:8000/mailRepositories/cassandra%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails'
-....
+[subs=attributes+]
+----
+curl -XGET 'http://ip:8000/mailRepositories/{mailet-repository-path-prefix}%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].
+See xref:{pages-path}/operate/webadmin.adoc#_listing_mails_contained_in_a_mail_repository[the documentation].
diff --git a/docs/modules/servers/pages/distributed/configure/search.adoc b/docs/modules/servers/partials/configure/search.adoc
similarity index 88%
copy from docs/modules/servers/pages/distributed/configure/search.adoc
copy to docs/modules/servers/partials/configure/search.adoc
index 735b843bfa..239e266c21 100644
--- a/docs/modules/servers/pages/distributed/configure/search.adoc
+++ b/docs/modules/servers/partials/configure/search.adoc
@@ -1,6 +1,3 @@
-= Distributed James Server — Search configuration
-:navtitle: Search configuration
-
This configuration helps you configure the components used to back search.
.search.properties content
diff --git a/docs/modules/servers/pages/distributed/configure/sieve.adoc b/docs/modules/servers/partials/configure/sieve.adoc
similarity index 93%
copy from docs/modules/servers/pages/distributed/configure/sieve.adoc
copy to docs/modules/servers/partials/configure/sieve.adoc
index 3874f3c6c4..7ecd4c452f 100644
--- a/docs/modules/servers/pages/distributed/configure/sieve.adoc
+++ b/docs/modules/servers/partials/configure/sieve.adoc
@@ -1,6 +1,3 @@
-= Sieve
-:navtitle: Sieve
-
James servers are able to evaluate and execute Sieve scripts.
Sieve is an extensible mail filtering language. It's limited
@@ -26,7 +23,7 @@ To be correctly executed, please note that the *Sieve* mailet is required to be
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]
+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.</p>
@@ -35,7 +32,7 @@ can thus use compatible software to manage his Sieve scripts.</p>
*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]
+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.
diff --git a/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc b/docs/modules/servers/partials/configure/smtp-hooks.adoc
similarity index 90%
copy from docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
copy to docs/modules/servers/partials/configure/smtp-hooks.adoc
index 0cc5ef3c8e..a660051a1d 100644
--- a/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
+++ b/docs/modules/servers/partials/configure/smtp-hooks.adoc
@@ -1,8 +1,5 @@
-= 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
+{server-name} SMTP protocol stack in order to customize the way your SMTP server
behaves without of the box components.
== DNSRBLHandler
@@ -42,6 +39,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -59,10 +57,11 @@ Example configuration:
== DSN hooks
-The Distributed server has optional support for DSN (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
+The {server-name} has optional support for DSN (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
-Please read carefully xref:distributed/configure/dsn.adoc[this page].
+Please read carefully xref:{pages-path}/configure/dsn.adoc[this page].
+[source,xml]
....
<smtpserver enabled="true">
<...> <!-- The rest of your SMTP configuration, unchanged -->
@@ -77,7 +76,7 @@ Please read carefully xref:distributed/configure/dsn.adoc[this page].
</smtpserver>
....
-Note that a specific configuration of xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] is
+Note that a specific configuration of xref:{pages-path}/configure/mailetcontainer.adoc[mailetcontainer.xml] is
required as well to be spec compliant.
== MailPriorityHandler
@@ -92,6 +91,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -117,6 +117,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -138,6 +139,7 @@ This handler should be considered as unsupported.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -158,6 +160,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -175,6 +178,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -190,6 +194,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -210,6 +215,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -232,6 +238,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -252,6 +259,7 @@ This handler should be considered experimental.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -279,6 +287,7 @@ This handler should be considered stable.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -296,6 +305,7 @@ are allowed to relay. Default is false.
Example configuration:
+[source,xml]
....
<handlerchain>
<!-- ... -->
@@ -305,8 +315,9 @@ Example configuration:
== FUTURERELEASE hooks
-The Distributed server has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])
+The {server-name} has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])
+[source,xml]
....
<smtpserver enabled="true">
<...> <!-- The rest of your SMTP configuration, unchanged -->
@@ -336,15 +347,16 @@ Supported configuration elements:
Example handlerchain configuration for `smtpserver.xml`:
-....xml
+[source,xml]
+....
<handlerchain>
-<handler class="org.apache.james.smtpserver.DKIMHook">
-<forceCLRF>true</forceCLRF>
-<onlyForSenderDomain>apache.org</onlyForSenderDomain>
-<signatureRequired>true</signatureRequired>
-<expectedDToken>apache.org</expectedDToken>
-</handler>
-<handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
+ <handler class="org.apache.james.smtpserver.DKIMHook">
+ <forceCLRF>true</forceCLRF>
+ <onlyForSenderDomain>apache.org</onlyForSenderDomain>
+ <signatureRequired>true</signatureRequired>
+ <expectedDToken>apache.org</expectedDToken>
+ </handler>
+ <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
</handlerchain>
....
diff --git a/docs/modules/servers/pages/distributed/configure/smtp.adoc b/docs/modules/servers/partials/configure/smtp.adoc
similarity index 95%
copy from docs/modules/servers/pages/distributed/configure/smtp.adoc
copy to docs/modules/servers/partials/configure/smtp.adoc
index 34e2288714..d2d8d519c4 100644
--- a/docs/modules/servers/pages/distributed/configure/smtp.adoc
+++ b/docs/modules/servers/partials/configure/smtp.adoc
@@ -1,9 +1,6 @@
-= 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]
+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.
@@ -177,7 +174,7 @@ MAIL command is accepted. If unspecified, the value defaults to true.
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
+| 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
@@ -233,9 +230,9 @@ At this time Apache James Server only supports simple user name / password authe
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*].
+xref:{pages-path}/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
+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
@@ -262,7 +259,7 @@ Eudora, Evolution).
== LMTP Configuration
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/lmtpserver.xml[example]
+Consult this link:{sample-configuration-prefix-url}/lmtpserver.xml[example]
to get some examples and hints.
The configuration is the same of for SMTP.
@@ -274,6 +271,7 @@ The default LMTP server stores directly emails in user mailboxes, without furthe
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]
....
<lmtpservers>
<lmtpserver enabled="true">
@@ -295,6 +293,7 @@ Note that by default the mailet container is executed with all recipients at onc
error reporting. An option <code>splitExecution</code> allow to execute the mailet container for each recipient separately and mitigate this
limitation at the cost of performance.
+[source,xml]
....
<lmtpservers>
<lmtpserver enabled="true">
diff --git a/docs/modules/servers/pages/distributed/configure/spam.adoc b/docs/modules/servers/partials/configure/spam.adoc
similarity index 96%
copy from docs/modules/servers/pages/distributed/configure/spam.adoc
copy to docs/modules/servers/partials/configure/spam.adoc
index 8a7839d604..5e5b8b2d6f 100644
--- a/docs/modules/servers/pages/distributed/configure/spam.adoc
+++ b/docs/modules/servers/partials/configure/spam.adoc
@@ -1,6 +1,3 @@
-= Distributed James Server — Anti-Spam configuration
-:navtitle: Anti-Spam configuration
-
Anti-Spam system can be configured via two main different mechanisms:
* SMTP Hooks;
@@ -67,7 +64,8 @@ If true `virusProcessor` and `rejectSpamProcessor` are honnered per user, at the
Here is an example of mailet pipeline conducting out RspamdScanner execution:
-....
+[subs=attributes+,xml]
+----
<processor state="local-delivery" enableJmx="true">
<mailet match="All" class="org.apache.james.rspamd.RspamdScanner">
<rewriteSubject>true</rewriteSubject>
@@ -100,18 +98,19 @@ Here is an example of mailet pipeline conducting out RspamdScanner execution:
<!--Store rejected spam emails (with a very high score) -->
<processor state="virus" enableJmx="false">
<mailet match="All" class="ToRepository">
- <repositoryPath>cassandra://var/mail/spam</repositoryPath>
+ <repositoryPath>{mailet-repository-path-prefix}://var/mail/spam</repositoryPath>
</mailet>
</processor>
-....
+----
==== 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].
+The Rspamd listener needs to explicitly be registered with xref:{pages-path}/configure/listeners.adoc[listeners.xml].
Example:
+[source,xml]
....
<listeners>
<listener>
@@ -128,6 +127,7 @@ Alternatively, batch reports can be triggered on user mailbox content via webAdm
=== SpamAssassin
Here is an example of mailet pipeline conducting out SpamAssassin execution:
+[source,xml]
....
<mailet match="All" class="SpamAssassin">
<onMailetException>ignore</onMailetException>
@@ -176,10 +176,11 @@ The SpamAssassin listener requires an extra configuration file `spamassassin.pro
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].
+The SpamAssassin listener needs to explicitly be registered with xref:{pages-path}/configure/listeners.adoc[listeners.xml].
Example:
+[source,xml]
....
<listeners>
<listener>
diff --git a/docs/modules/servers/pages/distributed/configure/ssl.adoc b/docs/modules/servers/partials/configure/ssl.adoc
similarity index 96%
copy from docs/modules/servers/pages/distributed/configure/ssl.adoc
copy to docs/modules/servers/partials/configure/ssl.adoc
index b21a17fa3a..df740c26bb 100644
--- a/docs/modules/servers/pages/distributed/configure/ssl.adoc
+++ b/docs/modules/servers/partials/configure/ssl.adoc
@@ -1,13 +1,10 @@
-= 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]
+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
@@ -20,6 +17,7 @@ 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]
....
<tls socketTLS="false" startTLS="true">
<keystore>file://conf/keystore</keystore>
@@ -31,6 +29,7 @@ You need to add a block in the corresponding configuration file (smtpserver.xml,
Alternatively TLS keys can be supplied via PEM files:
+[source,xml]
....
<tls socketTLS="true" startTLS="false">
<privateKey>file://conf/private.key</privateKey>
@@ -40,6 +39,7 @@ Alternatively TLS keys can be supplied via PEM files:
An optional secret might be specified for the private key:
+[source,xml]
....
<tls socketTLS="true" startTLS="false">
<privateKey>file://conf/private.key</privateKey>
@@ -50,6 +50,8 @@ An optional secret might be specified for the private key:
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]
....
<tls socketTLS="true" startTLS="false">
<supportedProtocols>
@@ -92,6 +94,7 @@ You will now need to create your certificate store and place it in the james/con
Please note `JKS` keystore format is also supported (default value if no keystore type is specified):
+[source,xml]
....
<tls socketTLS="false" startTLS="true">
<keystore>file://conf/keystore</keystore>
@@ -106,6 +109,7 @@ Please note `JKS` keystore format is also supported (default value if no keystor
When you enable TLS, you may also configure the server to require a client certificate for authentication:
+[source,xml]
....
<tls socketTLS="false" startTLS="true">
<keystore>file://conf/keystore</keystore>
@@ -130,6 +134,7 @@ in the certificate itself.
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
@@ -147,6 +152,7 @@ openssl rsa -in private.key -out private.nopass.key
You may then supply this TLS configuration:
+[source,xml]
....
<tls socketTLS="true" startTLS="false">
<privateKey>file://conf/private.nopass.key</privateKey>
diff --git a/docs/modules/servers/partials/configure/systemPropertiesPartial.adoc b/docs/modules/servers/partials/configure/systemPropertiesPartial.adoc
new file mode 100644
index 0000000000..40648e9b9d
--- /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/pages/distributed/configure/tika.adoc b/docs/modules/servers/partials/configure/tika.adoc
similarity index 95%
copy from docs/modules/servers/pages/distributed/configure/tika.adoc
copy to docs/modules/servers/partials/configure/tika.adoc
index fdb2cc9cf7..4e2ae16662 100644
--- a/docs/modules/servers/pages/distributed/configure/tika.adoc
+++ b/docs/modules/servers/partials/configure/tika.adoc
@@ -1,6 +1,3 @@
-= 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.
diff --git a/docs/modules/servers/pages/distributed/configure/usersrepository.adoc b/docs/modules/servers/partials/configure/usersrepository.adoc
similarity index 93%
copy from docs/modules/servers/pages/distributed/configure/usersrepository.adoc
copy to docs/modules/servers/partials/configure/usersrepository.adoc
index 08f8f674ed..e8d40e67a6 100644
--- a/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
+++ b/docs/modules/servers/partials/configure/usersrepository.adoc
@@ -1,9 +1,6 @@
-= 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]
+Consult this link:{sample-configuration-prefix-url}/usersrepository.xml[example]
to get some examples and hints.
== The user data model
@@ -54,11 +51,12 @@ Note: When using `PBKDF2` or `PBKDF2-SHA512` one can specify the iteration count
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]
+Consult this link:{sample-configuration-prefix-url}/usersrepository.xml[example]
to get some examples and hints.
Example:
+[source,xml]
....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid">
@@ -71,6 +69,7 @@ SSL can be enabled by using `ldaps` scheme. `trustAllCerts` option can be used t
Example:
+[source,xml]
....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldaps://myldapserver:636"
principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
@@ -81,6 +80,7 @@ Example:
Moreover, per domain base DN can be configured:
+[source,xml]
....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
@@ -95,6 +95,7 @@ You can connect to multiple LDAP servers for better availability by using `ldapH
Example:
+[source,xml]
....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636"
principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid" trustAllCerts="true">
@@ -107,6 +108,7 @@ This is the LDAP attribute that allows to retrieve the local part of users. Opti
Example:
+[source,xml]
....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636"
principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" resolveLocalPartAttribute="uid" userIdAttribute="mail" trustAllCerts="true">
diff --git a/docs/modules/servers/pages/distributed/configure/vault.adoc b/docs/modules/servers/partials/configure/vault.adoc
similarity index 61%
copy from docs/modules/servers/pages/distributed/configure/vault.adoc
copy to docs/modules/servers/partials/configure/vault.adoc
index b65a4c347d..b631222e74 100644
--- a/docs/modules/servers/pages/distributed/configure/vault.adoc
+++ b/docs/modules/servers/partials/configure/vault.adoc
@@ -1,23 +1,20 @@
-= 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].
+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 Cassandra. For configuring the BlobStore the vault will use, you can look at
-xref:distributed/configure/blobstore.adoc[*blobstore.properties*] BlobStore Configuration section.
+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:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/deletedMessageVault.properties[example]
+Consult this link:{sample-configuration-prefix-url}/deletedMessageVault.properties[example]
to get some examples and hints.
.deletedMessageVault.properties content
diff --git a/docs/modules/servers/pages/distributed/configure/webadmin.adoc b/docs/modules/servers/partials/configure/webadmin.adoc
similarity index 80%
copy from docs/modules/servers/pages/distributed/configure/webadmin.adoc
copy to docs/modules/servers/partials/configure/webadmin.adoc
index 01477845c3..61da6ed21f 100644
--- a/docs/modules/servers/pages/distributed/configure/webadmin.adoc
+++ b/docs/modules/servers/partials/configure/webadmin.adoc
@@ -1,8 +1,12 @@
-= Distributed James Server — webadmin.properties
-:navtitle: webadmin.properties
+The web administration supports for now the CRUD operations on:
-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.
+- 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
@@ -13,7 +17,7 @@ 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]
+Consult this link:{sample-configuration-prefix-url}/webadmin.properties[example]
to get some examples and hints.
.webadmin.properties content
@@ -61,7 +65,7 @@ Defaults to the `jwt.publickeypem.url` value of `jmap.properties` file if unspec
| 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:distributed/extending/webadmin-routes.adoc[creating you own webadmin routes].
+xref:{pages-path}/extending/webadmin-routes.adoc[creating you own webadmin routes].
| maxThreadCount
| Maximum threads used by the underlying Jetty server. Optional.
@@ -73,7 +77,7 @@ xref:distributed/extending/webadmin-routes.adoc[creating you own webadmin routes
== Generating a JWT key pair
-The Distributed server enforces the use of RSA-SHA-256.
+The {server-name} enforces the use of RSA-SHA-256.
One can use OpenSSL to generate a JWT key pair :
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org