Debian Codegraph @

doc/html/_sources/imap/concepts/features/server-aggregation.rst.txt

raw
1 .. _imap-features-murder:
2
3 ======================================
4 Cyrus IMAP Murder (Server Aggregation)
5 ======================================
6
7 A Cyrus IMAP Murder consists of a group of Cyrus IMAP servers
8 functioning as one large, transparent IMAP cluster.
9
10 In a Cyrus IMAP Murder, one or more servers with a *frontend* role
11 receive client connections, and proxy connections through to one of the
12 servers with a *backend* role -- these host the payload for the cluster
13 -- on the basis of where the current mailbox selected resides.
14
15 This makes access to mailboxes transparent to the client, even though
16 different mailboxes to which the user has access reside on different
17 servers.
18
19 To illustrate, let John's IMAP client connect to ``imap.example.org``:
20
21 .. graphviz::
22
23 digraph john {
24 rankdir = LR;
25 splines = true;
26 overlab = prism;
27
28 edge [color=gray50, fontname=Calibri, fontsize=11];
29 node [shape=record, fontname=Calibri, fontsize=11];
30
31 "Desktop Client" -> "imap.example.org" [label="Client Connection"];
32 }
33
34 John's mailbox may not reside on the node that the client connects to,
35 though, and instead be located on a :term:`backend` node -- as is
36 typical for larger deployments.
37
38 The client connection is therefore to be proxied to the appropriate
39 :term:`backend` node.
40
41 .. graphviz::
42
43 digraph john {
44 rankdir = LR;
45 splines = true;
46 overlab = prism;
47
48 edge [color=gray50, fontname=Calibri, fontsize=11];
49 node [shape=record, fontname=Calibri, fontsize=11];
50
51 "Desktop Client" -> "imap.example.org" [label="Client Connection"];
52 "imap.example.org" -> "backend1.example.org" [label="Proxied Connection"];
53 }
54
55 It is not at all uncommon to (reverse) proxy client connections like
56 this (a task that ``imap.example.org`` takes on in this example).
57
58 In the case of webservers for example, reverse proxying is a very
59 common practice:
60
61 .. graphviz::
62
63 digraph www {
64 rankdir = LR;
65 splines = true;
66 overlab = prism;
67
68 edge [color=gray50, fontname=Calibri, fontsize=11];
69 node [shape=record, fontname=Calibri, fontsize=11];
70
71 "Desktop Browser" -> "http://www.example.org/" [label="Client Connection"];
72
73 "http://www.example.org/" -> "assets1.example.org" [label="Static Content"];
74 "http://www.example.org/" -> "www1.example.org" [label="Dynamic Content"];
75 }
76
77 In the case of reverse web proxies, the proxy looks at (for example)
78 the request URI, and based on a set of rules, forwards (proxies) the
79 request on to the appropriate (internal) node. This architecture allows
80 application servers (www[0-9]+.example.org) to be scaled up and down by
81 application processing needs *separately* from the few web servers
82 typically needed to serve static files such as images and scripts (that
83 require no server-side processing).
84
85 In the case of IMAP, a commonly used IMAP proxy is NGINX. However,
86 NGINX can proxy John's connection to only one backend at a time. NGINX
87 allows an external script to respond with a target backend address
88 based on the authentication of the user.
89
90 As such, NGINX is a socket proxy, and not a fully-featured
91 application proxy:
92
93 .. graphviz::
94
95 digraph joe {
96 rankdir = LR;
97 splines = true;
98 overlab = prism;
99
100 edge [color=gray50, fontname=Calibri, fontsize=11];
101 node [shape=record, fontname=Calibri, fontsize=11];
102
103 "imap.example.org" [label="imap.example.org\n(NGINX)"];
104 "backend1.example.org" [label="backend1.example.org\n(user/john)"];
105 "backend2.example.org" [label="backend2.example.org\n(user/jane)"];
106 "Desktop Client" -> "imap.example.org" [label="Client Connection"];
107 "imap.example.org" -> "backend1.example.org" [label="Proxied Connection",color="green"];
108 "imap.example.org" -> "backend2.example.org" [label="Not Available",color="red"];
109 }
110
111 This means that John could not open a mailbox that does not reside on
112 the same backend node his client connection is proxied to, and John nor
113 Jane can share their mailboxes with one another [#]_.
114
115 For the proxy to be fully-featured, the proxy would need to catch all
116 IMAP commands that John's client issues [#]_, and determine what is the
117 most appropriate backend to serve the request -- not unlike the
118 aforementioned web proxies.
119
120 So, when John's client issues a ``SELECT INBOX``, the connection is to
121 be proxied to ``backend1.example.org``, but when John's client is to
122 issue a ``SELECT "Other Users/jane"``, the connection is to be proxied
123 to ``backend2.example.org``.
124
125 **This** is where the Cyrus IMAP Murder functionality kicks in:
126
127 * Mailbox location data is maintained through a central MUPDATE
128 server.
129
130 Each backend submits its list of local mailboxes when it starts up,
131 and maintains new, renamed and deleted mail folders, and Access
132 Control List (ACL) changes while running.
133
134 * The MUPDATE server replicates its aggregated database from across
135 all backends to all nodes with a :term:`frontend` role.
136
137 * Nodes with a :term:`frontend` role capture connections on the
138 protocol level and decide where the connection needs to be proxied
139 to
140
141 * Nodes with a :term:`frontend` role also arbiter between backends
142 when a message is moved from John's ``INBOX`` to Jane's ``INBOX`` or
143 vice-versa.
144
145 Use-Cases for the Cyrus IMAP Murder
146 ===================================
147
148 * Transparent access to content distributed over multiple (backend)
149 nodes,
150
151 * Sharing content distributed over multiple nodes (calendars, address
152 books, mail folders),
153
154 * High-availability and/or load-balanced frontends,
155
156 * Transport Layer Security termination, so frontends do connection
157 encryption and backends spend CPU cycles on mailboxes.
158
159 * Access Control enforcement at the perimeter
160
161 Administrators of larger infrastructures will be aware of the fact that
162 vertical scaling a single node only stretches so far.
163
164 When mail environments are to serve many thousands of users' mailboxes
165 (or more), multiple nodes are put to purpose, effectively scaling
166 horizontally rather than vertically.
167
168 In such environments it is likely that multiple backends are used to
169 store mailboxes, and depending on the requirements for the environment,
170 users with mailboxes distributed over these backends may be required to
171 share content with one another -- shared folders.
172
173 Should John be required to be able to share one or more of his mailboxes
174 with Jane, or vice-versa, one could attempt to ensure both users'
175 mailboxes reside on the same backend node (read: both users' client
176 connections are proxied to the same backend node).
177
178 In larger environments however (again), users that are required to be
179 able to share content often results in groups of several dozens,
180 hundreds or even thousands, making it very, very hard to maintain.
181
182 Cyrus IMAP Murder Topologies
183 ============================
184
185 A Cyrus IMAP Murder topology serves the need to **aggregate** the
186 mailboxes hosted by more than one Cyrus IMAP server with the *backend*
187 role.
188
189 Cyrus IMAP can do so in either one of three topologies:
190
191 #. :ref:`imap-features-murder-discrete`
192
193 The frontend and backend servers are separate.
194
195 #. :ref:`imap-features-murder-replicated`
196
197 All backends have access to all mailboxes.
198
199 #. :ref:`imap-features-murder-unified`
200
201 There's no distinction between backends and frontends, and all
202 backends perform frontend roles, but not all frontends are
203 automatically also backends.
204
205 .. NOTE::
206
207 In the context of a Cyrus IMAP Murder, the terms *frontend* and
208 *backend* are server roles, and while these roles may be performed
209 by separate servers, such as in a
210 :ref:`imap-features-murder-discrete`, but they need not be, such as
211 in a :ref:`imap-features-murder-unified`.
212
213 All Cyrus IMAP Murder topologies exchange information about where
214 mailboxes reside through the MUPDATE protocol (:rfc:`3656`).
215
216 .. _imap-features-murder-discrete:
217
218 Discrete Murder
219 ---------------
220
221 The simplest discrete murder topology puts each role on one or more
222 separate systems;
223
224 * the MUPDATE master (m),
225
226 * one or more frontend servers (f),
227
228 * one or more backend servers (b).
229
230 Each of the systems communicates with one another via the following
231 connection model:
232
233 .. graphviz::
234 :caption: Connection model for a Discrete Murder topology
235
236 digraph {
237 rankdir=LR;
238 nodesep=2;
239
240 splines = true;
241 overlab = prism;
242
243 edge [color=gray50, fontname=Calibri, fontsize=11];
244 node [shape=record, fontname=Calibri, fontsize=11];
245
246 "m" -> "f+" [dir=back];
247 "m" -> "b+" [dir=back];
248
249 "f+" -> "b+";
250 }
251
252 (1) A frontend (f) connects to the mupdate (m) master server and
253 receives updates from the mupdate master server.
254
255 The frontend continues to receive updates about deleted, renamed or
256 created mailboxes for as long as the connection from the frontend to
257 the mupdate master server exists.
258
259 The frontend reconnects if the connection is interrupted.
260
261 (2) A backend connects to the mupdate master server and pushes updates
262 to the mupdate server.
263
264 A backend reconnects to the mupdate master server as needed.
265
266 Murder Backend Startup Process
267 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268
269 .. graphviz::
270 :caption: Communication during Backend startup (1)
271
272 digraph {
273 rankdir=LR;
274 nodesep=2;
275
276 splines = true;
277 overlab = prism;
278
279 edge [color=gray50, fontname=Calibri, fontsize=11];
280 node [shape=record, fontname=Calibri, fontsize=11];
281
282 "m" -> "f+" [color=white];
283 "m" -> "b+" [color=red,dir=back,label="(1)"];
284
285 "f+" -> "b+" [color=white];
286 }
287
288 .. graphviz::
289 :caption: Communication during Backend startup (2)
290
291 digraph {
292 rankdir=LR;
293 nodesep=2;
294
295 splines = true;
296 overlab = prism;
297
298 edge [color=gray50, fontname=Calibri, fontsize=11];
299 node [shape=record, fontname=Calibri, fontsize=11];
300
301
302 "m" -> "f+" [color=red,label="(2)"];
303 "m" -> "b+" [color=green,dir=back,label="(1)"];
304
305 "f+" -> "b+" [color=white];
306 }
307
308 (1) The backend (b) pushes its list of mailboxes to the mupdate master
309 (m) using ``ctl_mboxlist -m``.
310
311 The list of local mailboxes on the backend is routinely compared
312 with the current state of the rest of the murder topology;
313
314 * Mailboxes that exist locally but are not in MUPDATE are pushed
315 to the mupdate master server.
316
317 * Mailboxes that exist locally but for which the mupdate master
318 server has an entry for the mailbox to live on a different
319 server are deleted locally.
320
321 .. NOTE::
322
323 Additional options to
324 :ref:`imap-reference-manpages-systemcommands-ctl_mboxlist` allow the deletion
325 to be prevented.
326
327 * Mailboxes that do not exist locally but exists in MUPDATE as
328 living locally are removed from the mupdate master server.
329
330 (2) The mupdate (m) master server pushes updates to the existing list of
331 mailboxes to the frontend (f) server.
332
333 .. graphviz::
334
335 digraph {
336 rankdir=LR;
337 nodesep=2;
338
339 splines = true;
340 overlab = prism;
341
342 edge [color=gray50, fontname=Calibri, fontsize=11];
343 node [shape=record, fontname=Calibri, fontsize=11];
344
345 "m" -> "f+" [dir=both];
346 "m" -> "b+" [dir=both];
347
348 "f+" -> "b+" [dir=both];
349 }
350
351 .. _imap-features-murder-replicated:
352
353 Replicated Murder
354 -----------------
355
356 .. NOTE::
357
358 This section needs to be written. Would you like to :ref:`help out <contribute-docs>`?
359
360 .. todo:: Please write me.
361
362 .. _imap-features-murder-unified:
363
364 Unified Murder
365 --------------
366
367 .. NOTE::
368
369 This section needs to be written. Would you like to :ref:`help out <contribute-docs>`?
370
371 .. todo:: Please write me.
372
373 Back to :ref:`imap-features`
374
375 .. rubric:: Footnotes
376
377 .. [#]
378
379 More literally speaking, John and Jane can *share*, just neither can
380 make use of the privilege.
381
382 .. [#]
383
384 Including but not limited to ``SELECT``, ``UID MOVE``, ``RENAME``,
385 etc.