"Fossies" - the Fresh Open Source Software Archive 
Member "courier-1.2.2/libs/imap/README.proxy" (20 Jan 2022, 8240 Bytes) of package /linux/misc/courier-1.2.2.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Link: Chapter 1. The Courier IMAP/POP3 proxy (start)
2 Link: Requirements (next)
3
4 Chapter 1. The Courier IMAP/POP3 proxy
5
6 Table of Contents
7
8 Requirements
9
10 Configuration
11
12 Using the same configuration files on all servers
13
14 Alternative configurations
15
16 Homogenous environments
17
18 Heterogenous environments
19
20 The Courier IMAP and POP3 servers now include a built-in proxy aggregator.
21 With a proxy aggregator, the mail accounts are split between multiple,
22 independent servers, with an IMAP/POP3 server running on each individual
23 server. A separate, proxy server sits in front and accepts ordinary IMAP
24 and POP3 connections. It reads the login ID, determines which server the
25 account is located on, connects to the server, and logs in. Then, for the
26 lifetime on the login session the front-end server takes itself out of the
27 loop, and forwards all session traffic between the IMAP/POP3 client, and
28 the back-end server.
29
30 Requirements
31
32 The Courier mail server can operate in IMAP/POP3 proxy mode only when the
33 Courier Authentication Library uses the userdb, LDAP, MySQL, or the
34 PostgreSQL authentication module. Challenge-Response (CRAM) authentication
35 will also work with the LDAP, MySQL, or the PostgreSQL authentication
36 module. Yes, CRAM authentication will work (except for userdb).
37
38 Configuration
39
40 Follow the regular installation instructions to set up The Courier mail
41 server with the actual mail accounts. The proxy feature uses the “account
42 options” feature of the Courier Authentication Library, specifically an
43 option called “mailhost”. Account option configuration process depends on
44 the authentication module. With userdb, account options are specified by
45 the “options” userdb attribute:
46
47 userdb user@example.com set options=mailhost=servera.example.com
48
49 Instructions for setting up account options with LDAP, MySQL, or
50 PostgreSQL, may be found in the appropriate configuration file. Briefly:
51
52 * In authldaprc, put “LDAP_AUXOPTIONS<TAB>mailhost=mailhost”, then
53 populate the “mailhost” LDAP attribute (this may entail modifications
54 of the LDAP schema).
55
56 * In authmysqlrc, put
57 “MYSQL_AUXOPTIONS<TAB>CONCAT("mailhost=",mailhost)” (or modify the
58 existing MYSQL_AUXOPTIONS setting accordingly), then create a
59 “mailhost” column in the account table.
60
61 * In authpgsqlrc, put “PGSQL_AUXOPTIONS<TAB>'mailhost=' || mailhost” (or
62 append ",mailhost=" || mailhost to an existing setting), then create a
63 “mailhost” column in the account table.
64
65 The “mailhost” option for each account should be the name of the server
66 where that account is located. If possible, this should match, exactly,
67 the PROXY_HOSTNAME environment variable or the value returned by the
68 “gethostname” on the server.
69
70 The final step is to set “IMAP_PROXY” and/or “POP3_PROXY” to “1” in the
71 imapd and/or the pop3d configuration file, in the Courier configuration
72 file directory on the proxy server.
73
74 Using the same configuration files on all servers
75
76 It is possible to have both the proxy server, and the back-end servers
77 with the actual accounts, read the same configuration file that enables
78 proxying. Ordinarily, if the back-end server also has the proxy setting
79 turned on, it will also attempt to establish a proxy connection (to
80 itself; lather, rinse, repeat until the server runs out of sockets).
81
82 However, if the “mailhost” option matches the server's hostname, as
83 returned by “gethostname”, no proxying takes place. Therefore, if specific
84 attention and care is made, when setting up the server names and account
85 options, all servers can boot off the same configuration file.
86
87 Alternative configurations
88
89 If the server names are set up properly, it's possible to set things up
90 without a dedicated front-end proxy aggregator server. All mail accounts
91 are divided between a pool of servers, who are just one, big, happy
92 family. IMAP and POP3 clients can connect to any server, at random. If
93 they try to log into an account that happens to reside on the same box,
94 then everything will be ready to go. If not, the server automatically
95 opens a proxy connection to the right box, and everything will be ready to
96 go as well.
97
98 Homogenous environments
99
100 Both servers involved in a proxy connections should be running the same
101 version of the Courier IMAP/POP3 server. The proxy code included in the
102 Courier-IMAP package tarball will talk to the server from the Courier-MTA
103 package tarball that includes the same build of the IMAP daemon, and
104 vice-versa. Run “imapd --version” to determine the build of the IMAP
105 daemon.
106
107 All servers MUST use the same identical imapd and pop3d configuration
108 files (with the possible exception of the proxy flag). The next section
109 explains why.
110
111 Heterogenous environments
112
113 It should generally be possible to have the The Courier IMAP/POP3 server
114 establish a proxy connection to some other third party, non-Courier, IMAP
115 or POP3 server. Of course, the Courier Authentication Library running on
116 the proxy server must have the same understanding of the account names and
117 passwords as the other IMAP/POP3 server. The main issue is the different
118 levels of protocol implementations.
119
120 Both the IMAP and POP3 protocols have optional features that different
121 servers may or may not implement. Some servers will implement certain
122 optional features of the IMAP or POP3 protocol; other servers will
123 implement different features parts.
124
125 When the IMAP/POP3 client connects to the server, the client typically
126 obtains the list of available optional features. After logging in, the
127 client will have no reason to expect that it's now talking to a different
128 server with a different set of protocol features. Therefore, it may not be
129 possible to use a Courier proxy with some other IMAP/POP3 server that
130 implements a widely different set of features. This may work with some
131 clients, that don't make use of optional features; while other clients
132 will report strange, or unpredictable errors.
133
134 In some cases, setting the IMAP_PROXY_FOREIGN flag, in the imapd
135 configuration file, may help. This command will send a message to the IMAP
136 client explicitly informing the client that the list of available protocol
137 features has changed; however some clients may ignore or not implement
138 this particular message. There is no equivalent POP3 command.
139
140 Note
141
142 As previously mentioned the IMAP/POP3 clients may use any supported
143 authentication method, including CRAM authentication (in most cases), with
144 or without encryption, to log in. However, Courier will always use plain
145 userid/password authentication, without encryption, to establish proxy
146 connections. When using a different server, that server must be configured
147 to allow plain userid/password authentication.
148
149 Note that the default configuration of the UW-IMAP server requires
150 encryption, and refuses non-encrypted connections. Proxy connections are
151 presumably carried over a private network, and there is no reason to use
152 encryption. Therefore, the UW-IMAP server will have to be re-configured to
153 allow non-encrypted connections, if it's to be used with Courier in proxy
154 mode.
155
156 References
157
158 Visible links
159 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#proxy
160 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#requirements
161 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#requirements
162 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#configuration
163 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#idm44912407468848
164 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#idm44912407530944
165 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#idm44912407529744
166 . file:///home/mrsam/src/courier.git/courier/libs/imap/README.proxy.html#idm44912407524720