server/apps/distributed-app/docs/modules/ROOT/pages/configure/imap.adoc - james-project - Git at Google

 = Distributed James Server &mdash; 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: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].
	= 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: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].