Link: Chapter 1. The Courier IMAP/POP3 proxy (start)
Link: Requirements (next)

Chapter 1. The Courier IMAP/POP3 proxy

Table of Contents

Requirements

Configuration

             Using the same configuration files on all servers

             Alternative configurations

             Homogenous environments

             Heterogenous environments

The Courier IMAP and POP3 servers now include a built-in proxy aggregator. With
a proxy aggregator, the mail accounts are split between multiple, independent
servers, with an IMAP/POP3 server running on each individual server. A separate,
proxy server sits in front and accepts ordinary IMAP and POP3 connections. It
reads the login ID, determines which server the account is located on, connects
to the server, and logs in. Then, for the lifetime on the login session the
front-end server takes itself out of the loop, and forwards all session traffic
between the IMAP/POP3 client, and the back-end server.

Requirements

The Courier mail server can operate in IMAP/POP3 proxy mode only when the
Courier Authentication Library uses the userdb, LDAP, MySQL, or the PostgreSQL
authentication module. Challenge-Response (CRAM) authentication will also work
with the LDAP, MySQL, or the PostgreSQL authentication module. Yes, CRAM
authentication will work (except for userdb).

Configuration

Follow the regular installation instructions to set up The Courier mail server
with the actual mail accounts. The proxy feature uses the “account options”
feature of the Courier Authentication Library, specifically an option called
“mailhost”. Account option configuration process depends on the authentication
module. With userdb, account options are specified by the “options” userdb
attribute:

userdb user@example.com set options=mailhost=servera.example.com

Instructions for setting up account options with LDAP, MySQL, or PostgreSQL, may
be found in the appropriate configuration file. Briefly:

  • In authldaprc, put “LDAP_AUXOPTIONS<TAB>mailhost=mailhost”, then populate
    the “mailhost” LDAP attribute (this may entail modifications of the LDAP
    schema).

  • In authmysqlrc, put “MYSQL_AUXOPTIONS<TAB>CONCAT("mailhost=",mailhost)” (or
    modify the existing MYSQL_AUXOPTIONS setting accordingly), then create a
    “mailhost” column in the account table.

  • In authpgsqlrc, put “PGSQL_AUXOPTIONS<TAB>'mailhost=' || mailhost” (or
    append ",mailhost=" || mailhost to an existing setting), then create a
    “mailhost” column in the account table.

The “mailhost” option for each account should be the name of the server where
that account is located. If possible, this should match, exactly, the
PROXY_HOSTNAME environment variable or the value returned by the “gethostname”
on the server.

The final step is to set “IMAP_PROXY” and/or “POP3_PROXY” to “1” in the imapd
and/or the pop3d configuration file, in the Courier configuration file directory
on the proxy server.

  Using the same configuration files on all servers

It is possible to have both the proxy server, and the back-end servers with the
actual accounts, read the same configuration file that enables proxying.
Ordinarily, if the back-end server also has the proxy setting turned on, it will
also attempt to establish a proxy connection (to itself; lather, rinse, repeat
until the server runs out of sockets).

However, if the “mailhost” option matches the server's hostname, as returned by
“gethostname”, no proxying takes place. Therefore, if specific attention and
care is made, when setting up the server names and account options, all servers
can boot off the same configuration file.

  Alternative configurations

If the server names are set up properly, it's possible to set things up without
a dedicated front-end proxy aggregator server. All mail accounts are divided
between a pool of servers, who are just one, big, happy family. IMAP and POP3
clients can connect to any server, at random. If they try to log into an account
that happens to reside on the same box, then everything will be ready to go. If
not, the server automatically opens a proxy connection to the right box, and
everything will be ready to go as well.

  Homogenous environments

Both servers involved in a proxy connections should be running the same version
of the Courier IMAP/POP3 server. The proxy code included in the Courier-IMAP
package tarball will talk to the server from the Courier-MTA package tarball
that includes the same build of the IMAP daemon, and vice-versa. Run “imapd
--version” to determine the build of the IMAP daemon.

All servers MUST use the same identical imapd and pop3d configuration files
(with the possible exception of the proxy flag). The next section explains why.

  Heterogenous environments

It should generally be possible to have the The Courier IMAP/POP3 server
establish a proxy connection to some other third party, non-Courier, IMAP or
POP3 server. Of course, the Courier Authentication Library running on the proxy
server must have the same understanding of the account names and passwords as
the other IMAP/POP3 server. The main issue is the different levels of protocol
implementations.

Both the IMAP and POP3 protocols have optional features that different servers
may or may not implement. Some servers will implement certain optional features
of the IMAP or POP3 protocol; other servers will implement different features
parts.

When the IMAP/POP3 client connects to the server, the client typically obtains
the list of available optional features. After logging in, the client will have
no reason to expect that it's now talking to a different server with a different
set of protocol features. Therefore, it may not be possible to use a Courier
proxy with some other IMAP/POP3 server that implements a widely different set of
features. This may work with some clients, that don't make use of optional
features; while other clients will report strange, or unpredictable errors.

In some cases, setting the IMAP_PROXY_FOREIGN flag, in the imapd configuration
file, may help. This command will send a message to the IMAP client explicitly
informing the client that the list of available protocol features has changed;
however some clients may ignore or not implement this particular message. There
is no equivalent POP3 command.

  Note

As previously mentioned the IMAP/POP3 clients may use any supported
authentication method, including CRAM authentication (in most cases), with or
without encryption, to log in. However, Courier will always use plain
userid/password authentication, without encryption, to establish proxy
connections. When using a different server, that server must be configured to
allow plain userid/password authentication.

Note that the default configuration of the UW-IMAP server requires encryption,
and refuses non-encrypted connections. Proxy connections are presumably carried
over a private network, and there is no reason to use encryption. Therefore, the
UW-IMAP server will have to be re-configured to allow non-encrypted connections,
if it's to be used with Courier in proxy mode.

References

   Visible links
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#proxy
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#requirements
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#requirements
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#configuration
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#id1337
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#id1338
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#id1339
   . file:///home/mrsam/src/courier.git/courier-imap/libs/imap/README.proxy.html#id1340
