/usr/share/doc/courier-imap/README.proxy.html

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>The Courier IMAP/POP3 proxy</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"/><link rel="home" href="#proxy" title="The Courier IMAP/POP3 proxy"/><link rel="next" href="#requirements" title="Requirements"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
information.

--></head><body><div class="chapter" title="The Courier IMAP/POP3 proxy"><div class="titlepage"><div><div><h2 class="title"><a id="proxy" shape="rect"> </a>The <span class="application">Courier</span>
    IMAP/POP3 proxy</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#requirements" shape="rect">Requirements</a></span></dt><dt><span class="section"><a href="#configuration" shape="rect">Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#id529623" shape="rect">Using the same configuration files on all servers</a></span></dt><dt><span class="section"><a href="#id529648" shape="rect">Alternative configurations</a></span></dt><dt><span class="section"><a href="#id529662" shape="rect">Homogenous environments</a></span></dt><dt><span class="section"><a href="#id529704" shape="rect">Heterogenous environments</a></span></dt></dl></dd></dl></div><p>
The <span class="application">Courier</span>
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.</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirements" shape="rect"> </a>Requirements</h2></div></div></div><p>
The <span class="application">Courier</span>
mail server can operate in IMAP/POP3 proxy mode only
when the <span class="application">Courier</span> Authentication Library uses the
<code class="literal">userdb</code>,
<code class="literal">LDAP</code>,
<code class="literal">MySQL</code>, or the
<code class="literal">PostgreSQL</code> authentication module.
<span class="emphasis"><em>Challenge-Response (CRAM) authentication
will also work with the
<code class="literal">LDAP</code>,
<code class="literal">MySQL</code>, or the
<code class="literal">PostgreSQL</code> authentication module</em></span>.
Yes, CRAM authentication will work (except for <code class="literal">userdb</code>).</p></div><div class="section" title="Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuration" shape="rect"> </a>Configuration</h2></div></div></div><p>
Follow the regular installation instructions to set up
The <span class="application">Courier</span>
mail server with the actual mail accounts.
The proxy feature uses the <span class="quote">“<span class="quote">account options</span>”</span> feature of the
<span class="application">Courier</span> Authentication Library,
specifically an option called <span class="quote">“<span class="quote">mailhost</span>”</span>.
Account option configuration process depends on the authentication module.
With <code class="literal">userdb</code>, account options are specified by the
<span class="quote">“<span class="quote">options</span>”</span> <code class="literal">userdb</code> attribute:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
userdb user@example.com set options=mailhost=servera.example.com
</pre></div><p>
Instructions for setting up account options with
<code class="literal">LDAP</code>,
<code class="literal">MySQL</code>, or
<code class="literal">PostgreSQL</code>, may be found in the appropriate configuration
file.  Briefly:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
In <code class="filename">authldaprc</code>, put
<span class="quote">“<span class="quote">LDAP_AUXOPTIONS&lt;TAB&gt;mailhost=mailhost</span>”</span>,
then populate the <span class="quote">“<span class="quote">mailhost</span>”</span> LDAP attribute
(this may entail modifications of the LDAP schema).</p></li><li class="listitem"><p>
In <code class="filename">authmysqlrc</code>, put
<span class="quote">“<span class="quote">MYSQL_AUXOPTIONS&lt;TAB&gt;CONCAT("mailhost=",mailhost)</span>”</span>
(or modify the existing <code class="literal">MYSQL_AUXOPTIONS</code> setting
accordingly), then create a <span class="quote">“<span class="quote">mailhost</span>”</span> column in the account
table.</p></li><li class="listitem"><p>
In <code class="filename">authpgsqlrc</code>, put
<span class="quote">“<span class="quote">PGSQL_AUXOPTIONS&lt;TAB&gt;'mailhost=' || mailhost</span>”</span>
(or append <code class="literal">",mailhost=" || mailhost</code>
to an existing setting),
then create a <span class="quote">“<span class="quote">mailhost</span>”</span> column in the account
table.</p></li></ul></div><p>
The <span class="quote">“<span class="quote">mailhost</span>”</span> option for each account should be the name of
the server where that account is located.
If possible, this should match, <span class="emphasis"><em>exactly</em></span>,
the <code class="envar">PROXY_HOSTNAME</code> environment variable or the value
returned by the <span class="quote">“<span class="quote">gethostname</span>”</span> on the server.</p><p>
The final step is to set <span class="quote">“<span class="quote">IMAP_PROXY</span>”</span> and/or
<span class="quote">“<span class="quote">POP3_PROXY</span>”</span> to <span class="quote">“<span class="quote">1</span>”</span> in the
<code class="filename">imapd</code> and/or the <code class="filename">pop3d</code>
configuration file, in the Courier configuration file directory on
the proxy server.</p><div class="section" title="Using the same configuration files on all servers"><div class="titlepage"><div><div><h3 class="title"><a id="id529623" shape="rect"> </a>Using the same configuration files on all servers</h3></div></div></div><p>
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).</p><p>
However, if the <span class="quote">“<span class="quote">mailhost</span>”</span> option matches the server's hostname,
as returned by <span class="quote">“<span class="quote">gethostname</span>”</span>, 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.</p></div><div class="section" title="Alternative configurations"><div class="titlepage"><div><div><h3 class="title"><a id="id529648" shape="rect"> </a>Alternative configurations</h3></div></div></div><p>
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.</p></div><div class="section" title="Homogenous environments"><div class="titlepage"><div><div><h3 class="title"><a id="id529662" shape="rect"> </a>Homogenous environments</h3></div></div></div><p>
Both servers involved in a proxy connections should be running the
same version of the
<span class="application">Courier</span> 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 <span class="quote">“<span class="quote">imapd --version</span>”</span> to determine the build of the IMAP
daemon.</p><p>
All servers
<span class="emphasis"><em>MUST</em></span>
use the same identical <code class="filename">imapd</code>
and <code class="filename">pop3d</code> configuration files (with the possible
exception of the proxy flag).
The next section explains why.</p></div><div class="section" title="Heterogenous environments"><div class="titlepage"><div><div><h3 class="title"><a id="id529704" shape="rect"> </a>Heterogenous environments</h3></div></div></div><p>
It should generally be possible to have the
The <span class="application">Courier</span>
IMAP/POP3 server establish a proxy connection to some other third party,
non-<span class="application">Courier</span>, IMAP or POP3 server.
Of course, the <span class="application">Courier</span> 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.</p><p>
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.</p><p>
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.</p><p>
In some cases, setting the <code class="literal">IMAP_PROXY_FOREIGN</code> flag,
in
the <code class="filename">imapd</code> 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.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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.</p><p>
Note that the default configuration of the <code class="literal">UW-IMAP</code>
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 <code class="literal">UW-IMAP</code> server will have to be
re-configured to allow non-encrypted connections, if it's to be used
with Courier in proxy mode.</p></div></div></div></div></body></html>
courier-imap 4.10.0-20120615-1ubuntu7 / usr / share / doc / courier-imap / README.proxy.html
