| <?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 - Server Wide Configuration</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Server Wide Configuration"> |
| |
| <subsection name="Introduction"> |
| |
| <p>There are a number of global configuration files that do not fall into any one |
| component. They have effects that are global in scope across the server.</p> |
| |
| <p>Some of these files are crucial, while others can be ignored by any but the most sophisticated |
| server administrators.</p> |
| |
| </subsection> |
| |
| <subsection name="spring-server.xml"> |
| |
| <p>In James distribution, the spring files are located under conf/context folder and splitted into a main |
| file (james-server-context.xml) which imports 3 other files (1 per mailbox type): james-mailbox-jpa-context.xml, |
| james-mailbox-memory-context.xml.</p> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/container/spring/src/main/resources/META-INF/org/apache/james/spring-server.xml">spring-server.xml</a> in GIT to |
| get some examples and hints.</p> |
| |
| <p>spring beans files are the place where the Apache James Server wiring is done. It should be modified only by expert-users.</p> |
| |
| <p>In combination with james-database.properties and META-INF/persistence.xml, the datasource to access the database is defined in spring-server.xml</p> |
| |
| </subsection> |
| |
| <subsection name="james-database.properties"> |
| |
| <p>This configuration file is only relevant when using JPA, with Spring or Guice.</p> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/apps/spring-app/src/main/resources/james-database.properties">james-database.properties</a> in GIT to get some examples and hints.</p> |
| |
| <p>The database connection in database.properties</p> |
| |
| <p>James has the capacity to use a JDBC-compatible database for storage of both message and user |
| data. This section explains how to configure James to utilize a database for storage.</p> |
| |
| <p>To avoid vendor-specific issues, the JPA (Java Persistence Architecture) is used (using the Apache OpenJPA implementation).</p> |
| |
| <p>There must be a database instance accessible from the James server. An account with appropriate |
| privileges (select, insert, delete into tables, and on initial startup creation of tables) and |
| with sufficient quota for the data to be inserted into the database must be available.</p> |
| |
| <p>Also, since James will use JDBC to access the database, an appropriate JDBC driver must be |
| available for installation. You can place the JDBC driver jar in the conf/lib folder, it will |
| be automatically loaded.</p> |
| <p>Database configuration</p> |
| <dl> |
| <dt><strong>database.driverClassName</strong></dt> |
| <dd>The class name of the database driver to be used.</dd> |
| <dt><strong>database.url</strong></dt> |
| <dd>The JDBC connection URL for your database/driver.</dd> |
| <dt><strong>database.username</strong></dt> |
| <dd>The user id of the database account to be used by this connection.</dd> |
| <dt><strong>database.password</strong></dt> |
| <dd>The password of the database account to be used by this connection.</dd> |
| </dl> |
| |
| <p>NOTE: all<code>openjpa.*</code> properties will be passed to OpenJPA library as configuration See <a href="https://openjpa.apache.org/builds/3.2.2/apache-openjpa/docs/ref_guide_conf_openjpa.html">https://openjpa.apache.org/builds/3.2.2/apache-openjpa/docs/ref_guide_conf_openjpa.html</a> for a complete list </p> |
| |
| <p>The JPA datasource and connection pooling can be delegated to commons-dbcp2 - the library dependency has to be present in classpath for it to be enabled. dbcp2 properties can be configured through james-database.properties - all properties prefixed with <code>datasource.*</code> will be passed to DBCP2 library via <code>openjpa.ConnectionProperties</code> OpenJPA property. The corresponding definitions and default values can be found in the <a href="https://commons.apache.org/proper/commons-dbcp/configuration.html">dbcp documentation</a>, some of the properties (but not limited to)</p> |
| <ul> |
| <li>datasource.testOnBorrow</li> |
| <li>datasource.validationQueryTimeoutSec</li> |
| <li>datasource.validationQuery</li> |
| <li>datasource.initialSize</li> |
| <li>datasource.minIdle</li> |
| <li>datasource.maxTotal</li> |
| </ul> |
| <p>NOTE: Connection poolling requires that <code>openjpa.Multithreaded</code> property is set to <code>true</code> (default)</p> |
| <p>Note for postgresql databases: Add <code>standard_conforming_strings=off</code> to your postgresql.xml, otherwise you |
| will get <code>""Invalid escape string Hint: Escape string must be empty or one character. {prepstmnt 174928937 |
| SELECT t0.mailbox_id, t0.mailbox_highest_modseq, t0.mailbox_last_uid, t0.mailbox_name, t0.mailbox_namespace, |
| t0.mailbox_uid_validity, t0.user_name FROM public.james_mailbox t0 WHERE (t0.mailbox_name LIKE ? |
| ESCAPE '\\' AND t0.user_name = ? AND t0.mailbox_namespace = ?) [params=?, ?, ?]} [code=0, state=22025]"</code></p> |
| |
| <p>Attachment storage configuration</p> |
| <dl> |
| <dt><strong>attachmentStorage.enabled</strong></dt> |
| <dd>The attachment storage configuration for JPA is used to enable the implementation of the attachment storage mechanism. |
| *WARNING*: this configuration is not designed to store large binary content (no more than 1 GB of data), as it is not optimized for this purpose. |
| Optional, Allowed values are: `true` or `false`, defaults to `false`</dd> |
| </dl> |
| </subsection> |
| |
| <subsection name="META-INF/persistence.xml"> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/apps/spring-app/src/main/resources/META-INF/persistence.xml">META-INF/persistence.xml</a> in GIT to get some examples and hints.</p> |
| |
| <p>The JPA mapping and properties are defined in the in META-INF/persistence.xml.</p> |
| |
| <p>You can override the definition in external file and importing the external file in the persistence.xml (see jpa-mappings.xml provided example in GIT)</p> |
| |
| <source> |
| <mapping-file>META-INF/jpa-mappings.xml</mapping-file></source> |
| |
| </subsection> |
| |
| <subsection name="jmx.properties"> |
| |
| <p><b>Disclaimer: </b> 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> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/apps/spring-app/src/main/resources/jmx.properties">jmx.properties</a> in GIT to get some examples and hints.</p> |
| |
| <p>This is used to configure the JMX MBean server via which all management is achieved (also used by via the james-cli).</p> |
| |
| <dl> |
| <dt><strong>jmx.enabled</strong></dt> |
| <dd>(Guice only). Boolean. Should the JMX server be enabled? Defaults to `true`.</dd> |
| <dt><strong>jmx.address</strong></dt> |
| <dd>The IP address (host name) the MBean Server will bind/listen to.</dd> |
| <dt><strong>jmx.port</strong></dt> |
| <dd>The port number the MBean Server will bind/listen to.</dd> |
| </dl> |
| |
| <p>To access from a remote location, it has been reported that <code>-Dcom.sun.management.jmxremote.ssl=false</code> is |
| needed in the startup script. Exposing JMX remotely poses numerous security issues and as such is strongly discouraged.</p> |
| |
| <b>JMX Security</b> |
| |
| <p>In order to set up JMX authentication, we need to put <code>jmxremote.password</code> and <code>jmxremote.access</code> file |
| to <code>/conf</code> directory.</p> |
| |
| <p><code>jmxremote.password</code>: define the username and password, that will be used by the client (here is james-cli)</p> |
| |
| <p>File's content example:</p> |
| <pre><code> |
| james-admin pass1 |
| </code></pre> |
| |
| <p><code>jmxremote.access</code>: define the pair of username and access permission</p> |
| |
| <p>File's content example:</p> |
| <pre><code> |
| james-admin readwrite |
| </code></pre> |
| |
| <p>(Guice only) When James runs with option <code>-Djames.jmx.credential.generation=true</code>, James will automatically |
| generate <code>jmxremote.password</code> if the file does not exist. |
| Then the default username is <code>james-admin</code> and a random password. This option defaults to true.</p> |
| |
| <p>(Spring only) Presence of JMX credentials is compulsory to start the server.</p> |
| </subsection> |
| |
| <subsection name="sqlResources.xml"> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/apps/spring-app/src/main/resources/sqlResources.xml">sqlResources.xml</a> in GIT to get some examples and hints.</p> |
| |
| <p>This file is deprecated but some mailets... still need it. The standard way to access database |
| is JPA, but some functionalities are not yet migrated and still need the sqlResources.xml resources.</p> |
| |
| <p>The precise SQL statements used by Apache James Server to modify and view data stored in the database |
| are specified in sqlResources.xml file.</p> |
| |
| <p>If you are using a SQL database with unusual SQL commands or data types, you may |
| need to add special entries to this file. The James team |
| does try to keep sqlResources.xml updated, so if you do run into a |
| special case, please let us know.</p> |
| |
| <p>Also, if the database tables are not created a priori, but rather are to be created by James |
| upon startup, special attention should be paid to the "create table" statements in this file. Such |
| statements tend to be both very database and very database instance specific.</p> |
| |
| </subsection> |
| |
| <subsection name="jvm.properties"> |
| |
| <p>This configuration file is only relevant when using Guice.</p> |
| |
| <p>It may contain any additional system properties for tweaking JVM execution. |
| When you normally would add a command line option <code>-Dmy.property=whatever</code>, |
| you can put it in this file as <code>my.property=whatever</code> instead. |
| These properties will be added as system properties on server start.</p> |
| |
| <p>Note that in some rare cases this might not work, |
| when a property affects very early JVM start behaviour.</p> |
| |
| <p>For testing purposes, you may specify a different file path via the |
| command line option <code>-Dextra.props=/some/other/jvm.properties</code>.</p> |
| |
| <p>Some tuning can be done via system properties. This includes:</p> |
| |
| <dl> |
| <dt><strong>james.message.memory.threshold</strong></dt> |
| <dd>(Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB. <br/> |
| This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk. <br/> |
| 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. |
| </dd> |
| |
| <dt><strong>james.message.usememorycopy</strong></dt> |
| <dd>Optional. Boolean. Defaults to false. Recommended value is false. <br/> |
| Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold be copied to temporary files?</dd> |
| |
| <dt><strong>james.lifecycle.leak.detection.mode</strong></dt> |
| <dd>Optional. Allowed values are: none, simple, advanced, testing. Defaults to simple. <br/> |
| Mode level of resource leak detection. It is used to detect a resource not be disposed of before it's garbage-collected. Example `MimeMessageInputStreamSource` <br/> |
| - none: Disables resource leak detection.<br/> |
| - simple: Enables output a simplistic error log if a leak is encountered and would free the resources (default). <br/> |
| - advanced: Enables output an advanced error log implying the place of allocation of the underlying object and would free resources. <br/> |
| - testing: Enables output an advanced error log implying the place of allocation of the underlying object and rethrow an error, that action is being taken by the development team. <br/> |
| </dd> |
| |
| <dt><strong>james.protocols.mdc.hostname</strong></dt> |
| <dd>Optional. Boolean. Defaults to true. <br/> |
| 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.</dd> |
| |
| <dt><strong>james.blob.id.hash.encoding</strong></dt> |
| <dd>Optional. String. Defaults to base64Url. <br/> |
| The encoding type when encode blobId. The support value are: base16, hex, base32, base32Hex, base64, base64Url.</dd> |
| |
| <dt><strong>james.jmap.quota.draft.compatibility</strong></dt> |
| <dd>Optional. Boolean. Default to false. <br/> |
| This property allows to enable JMAP Quota draft compatibility for some JMAP clients and allow them a time window to adapt to the RFC-9245 JMAP Quota.</dd> |
| </dl> |
| |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |
| |
