Mailismus - Admin Guide

4.7 - IMAP Server

This Mailismus component implements an IMAP server (compliant with IMAP4 rev1), which provides remote access and manipulation for messages stored on the mailserver.

The IMAP server requires the Message-Store (see section §4.2) and Directory subsystems to be configured.
The only Directory config file it's concerned with is the users file (see section §4.10.1), which defines the login credentials for IMAP clients.

Mailismus supports the following IMAP extensions:
IDLE, NAMESPACE, CHILDREN, UNSELECT, LITERAL+

4.7.1 - Task Config

The top-level config of the IMAP task is outlined below.

<imap>
    <listeners>
        <listener name="IMAP">
            <server>
                ...
            </server>
            <ssl ... />
        </listener>
    </listeners>
</imap>

4.7.2 - Listener

The Listener is a generic NAF component that is documented in the NAF Guide (see §7 there).
The IMAP task typically only has one Listener, listening on the standard IMAP port of 143, but you may however choose to run separate listeners, eg. on ports 143 and 993 (pure SSL).

Note the following aspects of the IMAP task's listener:
• It's port attribute need not be specified, since in this context, it defaults to the standard IMAP ports of 143 or 993, depending on SSL mode.
Of course if there is more than one listener, you will have explicitly specify another port on the others.
• Likewise the server's class attribute is omitted, as it defaults to the Mailismus IMAP-Server class.

The optional SSL config block is also a generic NAF facility (see NAF Guide, section §8) and the only thing left to add here is the treatment of its latent and mandatory attributes in the context of the IMAP Server.
Note that Mailismus supports the IMAP STLS extension, whereby a client may switch to SSL mode after establishing the connection.

If latent is set to its default value of False, then connections will be established in SSL mode to start with.
If True, then Mailismus will advertise its support of the STLS extension, and will switch to SSL mode if the remote client asks it to.
If the client does initiate an upgrade to SSL mode, it must do so before authenticating.
If mandatory is set to True, then the IMAP Server will reject any attempts to authenticate until the connection is switched to SSL.
If False, then the client is not required to switch to SSL. It is up to the client to decide.

4.7.3 - IMAP Server

The server's config block is listed below, with largely default values.

<server>
    <transcript>%DIRLOG%/transcripts/imapserver-%DT%.log</transcript>
    <greet>Mailismus IMAP Ready</greet>
    <authtypes>login | sasl_plain | sasl_cram_md5 | sasl_external</authtypes>
    <authtypes_ssl>login | sasl_external | sasl_plain</authtypes_ssl>
    <newmailfreq>20s</newmailfreq>
    <authtimeout>1m</authtimeout>
    <timeout>30m</timeout>
    <keywords_dyn>true</keywords_dyn>
    <keywords_map>%DIRVAR%/imap/imapkeywords</keywords_map>
    <capa_idle>Y</capa_idle>
</server>

transcript
This file records a transcript of the IMAP protocol dialogue.
This config item supports the same attributes as the GreyLog loggers (rotation, buffering, etc - see GreyLog Guide).
This setting has no default and transcripts will be turned off if it is omitted.

greet
This specifies the greeting message which the IMAP server issues in response to new connections.
The default is as illustrated above.

authtypes
This specifies the authentication methods which clients are allowed to use (as advertised by the IMAP CAPABILITY command) and defaults to the full set of supported mechanisms as illustrated above.
The LOGIN method (NB: not case sensitive) refers to the LOGIN mechanism built into the IMAP protocol, and the remainder are SASL mechanisms supported for the IMAP AUTHENTICATE command.
The SASL-External mechanism only applies if SSL is in effect, and requires the client to supply its own X.509 certificate. The certificate's Common-Name attribute is taken as the username, and the existence of this username in our Directory is sufficient to authenticate the client.

The special value all means All and is equivalent to omitting this config item (as that is the default).
The special value - means None, and prevents any clients from logging in (although in that case, you might as well turn off your IMAP server!)

authtypes_ssl
This specifies the login methods which are only allowed in SSL mode, and is thus always a subset of the methods in the authtypes config item.
If SSL capability is not configured, then this defaults to SASL_EXTERNAL, ie. only SASL-External is forbidden (since it makes no sense in the absence of a certificate).
If SSL capability is configured and is mandatory (ie. connections are initially established in SSL mode), then this config item is superfluous, and defaults to being the same as authtypes.
If SSL capability is configured but latent (ie. the client has to explicitly switch to SSL mode via the IMAP STLS command), then this setting defaults to Login, SASL-Plain and External, as illustrated above, ie. only the snooper-proof SASL-CRAM-MD5 is allowed on an unencrypted session.

The special value all means all the login methods are restricted to SSL mode only, ie. no logins are permitted in non-SSL mode.
The special value - means None, ie. none of the login methods are restricted to SSL mode (though it still makes no sense for SASL-External, which will fail anyway without a certificate).

newmailfreq
This specifies the frequency with which the IMAP server checks for the arrival of new messages in the current folder.
It defaults to 20 seconds, and is only applicable when in the IDLE state (see IDLE extension).

authtimeout
This specifies the idle timeout during the authentication phase.
If the client is idle (ie. silent) longer than this, it will be disconnected.
Defaults to 1 minute.

timeout
This specifies the idle timeout once the authentication phase has been completed.
Defaults to 30 minutes. This is in line with the RFC-3501 recommendation, to reduce the polling traffic required by an idle client.

keywords_dyn
This enables IMAP keywords (user-defined flags) to be dynamically mapped to a single-character code and assigned to messages.
This is a system-wide mapping (ie. not restricted to one folder or one user) and once a character code has been assigned to a keyword, all subsequent refs to either the keyword or the character will be correlated with each other.
This setting defaults to Yes, but if set to False, then keywords are disabled, and any ones presented by the client (eg. in the IMAP STORE command) will be ignored.

keywords_map
This specifies the backing file that permanently records the mappings created by the keywords_dyn feature.
It defaults to the path illustrated above (under the standard NAF ./var directory) and there is no compelling reason to change that.

You can inspect the imapkeywords file to see the currently defined mappings.
Note that it omits the mappings between IMAP system flags (as opposed to user-defined ones) and Maildir suffix characters, as these are fixed and hard-coded.

capa_idle
Specifies whether the IMAP IDLE extension (RFC-2177) is enabled.
Enabled by default.