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.
Some of these files are crucial, while others can be ignored by any but the most sophisticated server administrators.
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.
Consult spring-server.xml in GIT to get some examples and hints.
spring beans files are the place where the Apache James Server wiring is done. It should be modified only by expert-users.
In combination with james-database.properties and META-INF/persistence.xml, the datasource to access the database is defined in spring-server.xml
This configuration file is only relevant when using JPA, with Spring or Guice.
Consult james-database.properties in GIT to get some examples and hints.
The database connection in database.properties
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.
To avoid vendor-specific issues, the JPA (Java Persistence Architecture) is used (using the Apache OpenJPA implementation).
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.
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.
Database configuration
NOTE: allopenjpa.* properties will be passed to OpenJPA library as configuration See https://openjpa.apache.org/builds/3.2.2/apache-openjpa/docs/ref_guide_conf_openjpa.html for a complete list
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 datasource.* will be passed to DBCP2 library via openjpa.ConnectionProperties OpenJPA property. The corresponding definitions and default values can be found in the dbcp documentation, some of the properties (but not limited to)
NOTE: Connection poolling requires that openjpa.Multithreaded property is set to true (default)
Note for postgresql databases: Add standard_conforming_strings=off to your postgresql.xml, otherwise you
will get ""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]"
Attachment storage configuration
Consult META-INF/persistence.xml in GIT to get some examples and hints.
The JPA mapping and properties are defined in the in META-INF/persistence.xml.
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)
<mapping-file>META-INF/jpa-mappings.xml</mapping-file>Disclaimer: JMX poses several security concerns and had been leveraged to conduct arbitrary code execution.
This threat is mitigated by not allowing remote connections to JMX, setting up authentication and pre-authentication filters.
However, we recommend to either run James in isolation (docker / own virtual machine) or disable JMX altogether.
James JMX endpoint provides command line utilities and exposes a few metrics, also available on the metric endpoint.
Consult jmx.properties in GIT to get some examples and hints.
This is used to configure the JMX MBean server via which all management is achieved (also used by via the james-cli).
To access from a remote location, it has been reported that -Dcom.sun.management.jmxremote.ssl=false is
needed in the startup script. Exposing JMX remotely poses numerous security issues and as such is strongly discouraged.
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
(Guice only) 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.
(Spring only) Presence of JMX credentials is compulsory to start the server.
Consult sqlResources.xml in GIT to get some examples and hints.
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.
The precise SQL statements used by Apache James Server to modify and view data stored in the database are specified in sqlResources.xml file.
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.
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.
This configuration file is only relevant when using Guice.
It 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.
Some tuning can be done via system properties. This includes: