| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <document> |
| |
| <properties> |
| <title>Apache James Server 3 - RabbitMQ Configuration</title> |
| </properties> |
| |
| <body> |
| |
| <section name="RabbitMQ Server Configuration"> |
| <p> |
| RabbitMQ is used in distributed James in order to have a distributed MailQueue and distributed Event dispatching system. |
| |
| This configuration helps you configure components using RabbitMQ in case you want to setup a distributed James. |
| And it is only applicable with Guice products. |
| </p> |
| <p> |
| Consult <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties">rabbitmq.properties</a> |
| in GIT to get some examples and hints. |
| </p> |
| |
| <p> |
| RabbitMQ Configuration |
| </p> |
| <dl> |
| <dt><strong>uri</strong></dt> |
| <dd> |
| the amqp URI pointing to RabbitMQ server. Details about amqp URI format is in <a href="https://www.rabbitmq.com/uri-spec.html">RabbitMQ URI Specification</a> |
| </dd> |
| |
| <dt><strong>management.uri</strong></dt> |
| <dd> |
| 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 <a href="https://www.rabbitmq.com/management.html#usage-ui">RabbitMQ Management URI</a> |
| </dd> |
| |
| <dt><strong>management.user</strong></dt> |
| <dd>username used to access management service</dd> |
| |
| <dt><strong>management.password</strong></dt> |
| <dd>password used to access management service</dd> |
| |
| <dt><strong>connection.pool.retries</strong></dt> |
| <dd>Configure retries count to retrieve a connection. Exponential backoff is performed between each retries. |
| Optional integer, defaults to 10</dd> |
| |
| <dt><strong>connection.pool.min.delay.ms</strong></dt> |
| <dd>Configure initial duration (in ms) between two connection retries. Exponential backoff is performed between each retries. |
| Optional integer, defaults to 100</dd> |
| |
| <dt><strong>channel.pool.retries</strong></dt> |
| <dd>Configure retries count to retrieve a channel. Exponential backoff is performed between each retries. |
| Optional integer, defaults to 3</dd> |
| |
| <dt><strong>channel.pool.min.delay.ms</strong></dt> |
| <dd>Configure initial duration (in ms) between two channel retries. Exponential backoff is performed between each retries. |
| Optional integer, defaults to 50</dd> |
| |
| <dt><strong>channel.pool.size</strong></dt> |
| <dd>Configure the size of the channel pool. |
| Optional integer, defaults to 3</dd> |
| |
| <dt><strong>ssl.enabled</strong></dt> |
| <dd>Is using ssl enabled |
| Optional boolean, defaults to false</dd> |
| |
| <dt><strong>ssl.management.enabled</strong></dt> |
| <dd>Is using ssl on management api enabled |
| Optional boolean, defaults to false</dd> |
| |
| <dt><strong>ssl.validation.strategy</strong></dt> |
| <dd>Configure the validation strategy used for rabbitmq connections. Possible values are default, ignore and override. |
| Optional string, defaults to using systemwide ssl configuration</dd> |
| |
| <dt><strong>ssl.truststore</strong></dt> |
| <dd>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</dd> |
| |
| <dt><strong>ssl.truststore.password</strong></dt> |
| <dd>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</dd> |
| |
| <dt><strong>ssl.hostname.verifier</strong></dt> |
| <dd>Configure host name verification. Possible options are default and accept_any_hostname |
| Optional string, defaults to subject alternative name host verifier</dd> |
| |
| |
| <dt><strong>ssl.keystore</strong></dt> |
| <dd>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</dd> |
| |
| <dt><strong>ssl.keystore.password</strong></dt> |
| <dd>Configure the keystore password. If configured then "ssl.keystore" must also be configured, |
| Optional string, defaults to empty string</dd> |
| |
| <dt><strong>quorum.queues.enable</strong></dt> |
| <dd>Boolean. Whether to activate Quorum queue usage for use cases that benefits from it (work queue). |
| Quorum queues enables high availability. |
| False (default value) results in the usage of classic queues.</dd> |
| |
| <dt><strong>quorum.queues.replication.factor</strong></dt> |
| <dd> Strictly positive integer. The replication factor to use when creating quorum queues.</dd> |
| |
| <dt><strong>hosts</strong></dt> |
| <dd>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</dd> |
| |
| <dt><strong>notification.queue.ttl</strong></dt> |
| <dd>Optional integer, defaults is 3600000. |
| 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. |
| Configure queue ttl (in ms). References: https://www.rabbitmq.com/ttl.html#queue-ttl.</dd> |
| </dl> |
| </section> |
| |
| <section name="RabbitMQ MailQueue Configuration"> |
| <p> |
| RabbitMQ MailQueue Configuration |
| </p> |
| <p> |
| 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. |
| </p> |
| <dl> |
| <dt><strong>cassandra.view.enabled</strong></dt> |
| <dd>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. |
| </dd> |
| |
| <dt><strong>mailqueue.view.sliceWindow</strong></dt> |
| <dd> |
| James divide 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 |
| <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties">rabbitmq.properties</a> |
| </dd> |
| |
| <dt><strong>mailqueue.view.bucketCount</strong></dt> |
| <dd> |
| 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 |
| <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties">rabbitmq.properties</a> |
| </dd> |
| |
| <dt><strong>mailqueue.view.updateBrowseStartPace</strong></dt> |
| <dd> |
| 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 |
| <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties">rabbitmq.properties</a> |
| </dd> |
| |
| <dt><strong>mailqueue.size.metricsEnabled</strong></dt> |
| <dd> |
| 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 have 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 |
| <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties">rabbitmq.properties</a> |
| </dd> |
| </dl> |
| </section> |
| |
| <section name="RabbitMQ Tasks Configuration"> |
| <p>Tasks are WebAdmin triggered long running jobs. RabbitMQ is used to organise their execution in a work queue, |
| with an exclusive consumer. |
| </p> |
| <dl> |
| <dt><strong>task.consumption.enabled</strong></dt> |
| <dd> |
| 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. |
| </dd> |
| <dt><strong>task.queue.consumer.timeout</strong></dt> |
| <dd> |
| 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. |
| </dd> |
| </dl> |
| </section> |
| |
| </body> |
| |
| </document> |