"Fossies" - the Fresh Open Source Software Archive 
"Fossies" - the Fresh Open Source Software Archive A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.
1 <?xml version="1.0"?> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>Chapter 1. The Courier IMAP/POP3 proxy</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#proxy" title="Chapter 1. The Courier IMAP/POP3 proxy"/><link rel="next" href="#requirements" title="Requirements"/></head><body><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="proxy" shape="rect"> </a>Chapter 1. The <span class="application">Courier</span> 3 IMAP/POP3 proxy</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><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="#idm44912407468848" shape="rect">Using the same configuration files on all servers</a></span></dt><dt><span class="section"><a href="#idm44912407530944" shape="rect">Alternative configurations</a></span></dt><dt><span class="section"><a href="#idm44912407529744" shape="rect">Homogenous environments</a></span></dt><dt><span class="section"><a href="#idm44912407524720" shape="rect">Heterogenous environments</a></span></dt></dl></dd></dl></div><p> 4 The <span class="application">Courier</span> 5 IMAP and POP3 servers now include a built-in proxy aggregator. 6 With a proxy aggregator, the mail accounts are split between multiple, 7 independent servers, with an IMAP/POP3 server running on each individual 8 server. 9 A separate, proxy server sits in front and accepts ordinary IMAP 10 and POP3 connections. It reads the login ID, determines which server the 11 account is located on, connects to the server, and logs in. 12 Then, for the lifetime on the login session the front-end server takes itself 13 out of the loop, and forwards all session traffic between the IMAP/POP3 14 client, and the back-end server.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirements" shape="rect"> </a>Requirements</h2></div></div></div><p> 15 The <span class="application">Courier</span> 16 mail server can operate in IMAP/POP3 proxy mode only 17 when the <span class="application">Courier</span> Authentication Library uses the 18 <code class="literal">userdb</code>, 19 <code class="literal">LDAP</code>, 20 <code class="literal">MySQL</code>, or the 21 <code class="literal">PostgreSQL</code> authentication module. 22 <span class="emphasis"><em>Challenge-Response (CRAM) authentication 23 will also work with the 24 <code class="literal">LDAP</code>, 25 <code class="literal">MySQL</code>, or the 26 <code class="literal">PostgreSQL</code> authentication module</em></span>. 27 Yes, CRAM authentication will work (except for <code class="literal">userdb</code>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuration" shape="rect"> </a>Configuration</h2></div></div></div><p> 28 Follow the regular installation instructions to set up 29 The <span class="application">Courier</span> 30 mail server with the actual mail accounts. 31 The proxy feature uses the <span class="quote">“<span class="quote">account options</span>”</span> feature of the 32 <span class="application">Courier</span> Authentication Library, 33 specifically an option called <span class="quote">“<span class="quote">mailhost</span>”</span>. 34 Account option configuration process depends on the authentication module. 35 With <code class="literal">userdb</code>, account options are specified by the 36 <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"> 37 userdb user@example.com set options=mailhost=servera.example.com 38 </pre></div><p> 39 Instructions for setting up account options with 40 <code class="literal">LDAP</code>, 41 <code class="literal">MySQL</code>, or 42 <code class="literal">PostgreSQL</code>, may be found in the appropriate configuration 43 file. Briefly:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 44 In <code class="filename">authldaprc</code>, put 45 <span class="quote">“<span class="quote">LDAP_AUXOPTIONS<TAB>mailhost=mailhost</span>”</span>, 46 then populate the <span class="quote">“<span class="quote">mailhost</span>”</span> LDAP attribute 47 (this may entail modifications of the LDAP schema).</p></li><li class="listitem"><p> 48 In <code class="filename">authmysqlrc</code>, put 49 <span class="quote">“<span class="quote">MYSQL_AUXOPTIONS<TAB>CONCAT("mailhost=",mailhost)</span>”</span> 50 (or modify the existing <code class="literal">MYSQL_AUXOPTIONS</code> setting 51 accordingly), then create a <span class="quote">“<span class="quote">mailhost</span>”</span> column in the account 52 table.</p></li><li class="listitem"><p> 53 In <code class="filename">authpgsqlrc</code>, put 54 <span class="quote">“<span class="quote">PGSQL_AUXOPTIONS<TAB>'mailhost=' || mailhost</span>”</span> 55 (or append <code class="literal">",mailhost=" || mailhost</code> 56 to an existing setting), 57 then create a <span class="quote">“<span class="quote">mailhost</span>”</span> column in the account 58 table.</p></li></ul></div><p> 59 The <span class="quote">“<span class="quote">mailhost</span>”</span> option for each account should be the name of 60 the server where that account is located. 61 If possible, this should match, <span class="emphasis"><em>exactly</em></span>, 62 the <code class="envar">PROXY_HOSTNAME</code> environment variable or the value 63 returned by the <span class="quote">“<span class="quote">gethostname</span>”</span> on the server.</p><p> 64 The final step is to set <span class="quote">“<span class="quote">IMAP_PROXY</span>”</span> and/or 65 <span class="quote">“<span class="quote">POP3_PROXY</span>”</span> to <span class="quote">“<span class="quote">1</span>”</span> in the 66 <code class="filename">imapd</code> and/or the <code class="filename">pop3d</code> 67 configuration file, in the Courier configuration file directory on 68 the proxy server.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm44912407468848" shape="rect"> </a>Using the same configuration files on all servers</h3></div></div></div><p> 69 It is possible to have both the proxy server, and the back-end servers with 70 the actual accounts, read the same configuration file that enables proxying. 71 Ordinarily, if the back-end server also has the proxy setting turned on, it 72 will also attempt to establish a proxy connection (to itself; 73 lather, rinse, repeat until the server runs out of sockets).</p><p> 74 However, if the <span class="quote">“<span class="quote">mailhost</span>”</span> option matches the server's hostname, 75 as returned by <span class="quote">“<span class="quote">gethostname</span>”</span>, no proxying takes place. 76 Therefore, if specific attention and care is made, when setting up the 77 server names and account options, all servers can boot off the 78 same configuration file.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm44912407530944" shape="rect"> </a>Alternative configurations</h3></div></div></div><p> 79 If the server names are set up properly, it's possible to set things up 80 without a dedicated front-end proxy aggregator server. 81 All mail accounts are divided between a pool of servers, who are just one, 82 big, happy family. 83 IMAP and POP3 clients can connect to any server, at random. 84 If they try to log into an account that happens to reside on the 85 same box, then everything will be ready to go. 86 If not, the server automatically opens a proxy connection to the right 87 box, and everything will be ready to go as well.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm44912407529744" shape="rect"> </a>Homogenous environments</h3></div></div></div><p> 88 Both servers involved in a proxy connections should be running the 89 same version of the 90 <span class="application">Courier</span> IMAP/POP3 server. 91 The proxy code included in the 92 Courier-IMAP package tarball will talk to 93 the server from the 94 Courier-MTA 95 package tarball that includes the same build of the IMAP daemon, and 96 vice-versa. 97 Run <span class="quote">“<span class="quote">imapd --version</span>”</span> to determine the build of the IMAP 98 daemon.</p><p> 99 All servers 100 <span class="emphasis"><em>MUST</em></span> 101 use the same identical <code class="filename">imapd</code> 102 and <code class="filename">pop3d</code> configuration files (with the possible 103 exception of the proxy flag). 104 The next section explains why.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm44912407524720" shape="rect"> </a>Heterogenous environments</h3></div></div></div><p> 105 It should generally be possible to have the 106 The <span class="application">Courier</span> 107 IMAP/POP3 server establish a proxy connection to some other third party, 108 non-<span class="application">Courier</span>, IMAP or POP3 server. 109 Of course, the <span class="application">Courier</span> Authentication Library 110 running on the proxy server must have the same understanding of the 111 account names and passwords as the other IMAP/POP3 server. 112 The main issue is the different levels of protocol implementations.</p><p> 113 Both the IMAP and POP3 protocols have optional features that different 114 servers may or may not implement. 115 Some servers will implement certain optional features of the IMAP or POP3 116 protocol; other servers will implement different features parts.</p><p> 117 When the IMAP/POP3 client connects to the server, the client typically 118 obtains the list of available optional features. 119 After logging in, the client will have no reason to expect that it's now 120 talking to a different server with a different set of protocol features. 121 Therefore, it may not be possible to use a Courier proxy with some 122 other IMAP/POP3 server that implements a widely different set of 123 features. 124 This may work with some clients, that don't make use of optional features; 125 while other clients will report strange, or unpredictable errors.</p><p> 126 In some cases, setting the <code class="literal">IMAP_PROXY_FOREIGN</code> flag, 127 in 128 the <code class="filename">imapd</code> configuration file, may help. 129 This command will send a message to the IMAP client explicitly informing 130 the client that the list of available protocol features has changed; 131 however some clients may ignore or not implement this particular message. 132 There is no equivalent POP3 command.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 133 As previously mentioned the IMAP/POP3 clients may use any supported 134 authentication method, including CRAM authentication (in most cases), 135 with or without encryption, to log in. 136 However, Courier will always use plain userid/password authentication, 137 without encryption, to establish proxy connections. 138 When using a different server, that server must be configured to allow 139 plain userid/password authentication.</p><p> 140 Note that the default configuration of the <code class="literal">UW-IMAP</code> 141 server requires encryption, and refuses non-encrypted connections. 142 Proxy connections are presumably carried over a private network, and 143 there is no reason to use encryption. 144 Therefore, the <code class="literal">UW-IMAP</code> server will have to be 145 re-configured to allow non-encrypted connections, if it's to be used 146 with Courier in proxy mode.</p></div></div></div></div></body></html>