1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Cyrus IMAP Server: Replication Examples — Cyrus IMAP 3.12.1 documentation</title>
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/underscore.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Cyrus IMAP Server: Replication Protocol v2.4+" href="replication_protocol.html" />
<link rel="prev" title="Cyrus IMAP Server: prot layer" href="prot.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home">
Cyrus IMAP
</a>
<div class="version">
3.12.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../setup.html">Setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../developers.html">Developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../contribute.html">We need your help</a></li>
<li class="toctree-l2"><a class="reference internal" href="../documentation.html">Contribute docs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer.html">Contribute code and tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cyrusworks.html">Cyrus.Works</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../../developers.html#cyrus-internals">Cyrus Internals</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../API.html">Cyrus APIs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../thoughts.html">Thoughts & Notes</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../guidance.html">Guidance for Developers</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="hacking.html">Cyrus IMAP Server: Hacking</a></li>
<li class="toctree-l4"><a class="reference internal" href="internationalization.html">Cyrus IMAP Server: Internationalization</a></li>
<li class="toctree-l4"><a class="reference internal" href="locking.html">Cyrus IMAP Server: Locking</a></li>
<li class="toctree-l4"><a class="reference internal" href="mailbox-format.html">Cyrus IMAP Server: Mailbox File Formats</a></li>
<li class="toctree-l4"><a class="reference internal" href="namelocks.html">Cyrus IMAP Server: Namelocks</a></li>
<li class="toctree-l4"><a class="reference internal" href="prot.html">Cyrus IMAP Server: prot layer</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">Cyrus IMAP Server: Replication Examples</a></li>
<li class="toctree-l4"><a class="reference internal" href="replication_protocol.html">Cyrus IMAP Server: Replication Protocol v2.4+</a></li>
<li class="toctree-l4"><a class="reference internal" href="special_chars.html">Cyrus IMAP Server: Special Characters</a></li>
<li class="toctree-l4"><a class="reference internal" href="var_directory_structure.html">Cyrus IMAP Server: var directory structure</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../developers.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">Cyrus IMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../../developers.html">Developers</a></li>
<li class="breadcrumb-item"><a href="../guidance.html">Developer Guidance</a></li>
<li class="breadcrumb-item active">Cyrus IMAP Server: Replication Examples</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/developer/guidance/replication_examples.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<span class="target" id="imap-developer-guidance-replication-examples"></span><section id="cyrus-imap-server-replication-examples">
<h1>Cyrus IMAP Server: Replication Examples<a class="headerlink" href="#cyrus-imap-server-replication-examples" title="Permalink to this heading"></a></h1>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this heading"></a></h2>
<p>The replication system creates a link between two Cyrus mailstores: a
master and a replica system. Both systems can be live mailstores with
active users: here in Cambridge we install systems in pairs.</p>
<p>Typically half of the users will be using each system, and each system
replicates to its partner. In the event of a failover everyone uses the
remaining system in a pair. This is typically safe as the IMAP/POP/SMTP
servers define which of the two systems is the live server for any given
account, and the replica just plays a game of follow my leader.</p>
<p>Occasionally I think about introducing some form of sanity check so that
we have to explicitly issue a command to the remaining backend system as
well as the proxies in the event of a failover.</p>
</section>
<section id="a-short-example-of-replication-in-action">
<h2>A short example of replication in action<a class="headerlink" href="#a-short-example-of-replication-in-action" title="Permalink to this heading"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Index:
#: Annotation
C: Command issued by client
S: Command issued by server
# Authentication between systems is done using SSH key based authentication:
C: $ ssh -x cyrus-2 /usr/local/cyrus/bin/sync_server
S: * Sync Server v0.0 [EXPERIMENTAL]
# Create new auth_state and ask for all information about given list of
# folders (namely user.dpc22). Returns:
#
# "**" unsolicited response for each mailbox. Returns:
# Folder UniqueID, Name, ACL, UIDlast, timestamp for last seen update.
#
# "*" response for each mail message in folder:
# UID, GUID, flags (other than \Seen state)
C: user_some dpc22 user.dpc22
S: ** 6b98205c796c6c61 user.dpc22 \
S: "dpc22 lrswipcda anonymous 0 " 4151 1062945305
S: * 1 000000000000000000000000 ()
S: * 3697 0101003f4c56b00545000000 ()
S: * 3919 0101003f4c56b04b2900000d ()
S: * 3937 0101003f4c56b0514900001f ()
S: * 4066 0101003f4c56b07422000002 ()
S: * 4089 0101003f4c56b07e56000023 (\answered)
S: * 4118 0101003f4c56b08328000016 ()
S: * 4131 0101003f4c56b084d7000002 ()
S: * 4136 0101003f4c56b087f3000001 ()
S: * 4140 0101003f4c56b08c9d000026 ()
S: OK User_Some finished
# Select a folder to work with
C: select user.dpc22
S: OK 6b98205c796c6c61 4151 1062945305
# Remove message with UID "1" from folder list (message which has been
# sitting in my inbox since January, has no GUID defined)
C: expunge 1
S: OK Expunge Complete
# Set some user flags on message UID "4140"
C: setflags 4140 (hello world)
S: OK Updated flags on 1 messages okay
# Demonstrate that something has changed:
C: status
S: * 3697 0101003f4c56b00545000000 ()
S: * 3919 0101003f4c56b04b2900000d ()
S: * 3937 0101003f4c56b0514900001f ()
S: * 4066 0101003f4c56b07422000002 ()
S: * 4089 0101003f4c56b07e56000023 (\answered)
S: * 4118 0101003f4c56b08328000016 ()
S: * 4131 0101003f4c56b084d7000002 ()
S: * 4136 0101003f4c56b087f3000001 ()
S: * 4140 0101003f4c56b08c9d000026 (hello world)
S: OK 4151
# Now lets correct the damage that we just inflicted:
C: $ replicate -s cyrus-2 -v -v -m user.dpc22
S: MAILBOXES user.dpc22
S: USER_SOME dpc22 user.dpc22
S: SELECT user.dpc22
S: SETFLAGS [1 msgs]
S: UPLOAD [1 msgs]
S: SETSEEN dpc22 ...
S: ENDUSER
C: $ ssh -x cyrus-2 /usr/local/cyrus/bin/sync_server
S: * Sync Server v0.0 [EXPERIMENTAL]
S: user_some dpc22 user.dpc22
S: ** 6b98205c796c6c61 user.dpc22 \
S: "dpc22 lrswipcda anonymous 0 " 4156 1062968731
S: * 1 000000000000000000000000 ()
S: * 3697 0101003f4c56b00545000000 ()
S: * 3919 0101003f4c56b04b2900000d ()
S: * 3937 0101003f4c56b0514900001f ()
S: * 4066 0101003f4c56b07422000002 ()
S: * 4089 0101003f4c56b07e56000023 (\answered)
S: * 4118 0101003f4c56b08328000016 ()
S: * 4131 0101003f4c56b084d7000002 ()
S: * 4136 0101003f4c56b087f3000001 ()
S: * 4140 0101003f4c56b08c9d000026 ()
S: OK User_Some finished
# Back where we started: the replication engine reinserted message UID 0
# which was missing, and removed "hello world" from message UID 4140
</pre></div>
</div>
</section>
<section id="tracking-messages-between-folders">
<h2>Tracking messages between folders<a class="headerlink" href="#tracking-messages-between-folders" title="Permalink to this heading"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># I've just saved a message from my inbox into a folder named "zzz",
# creating the folder the process.
C: $ replicate -s cyrus-2 -v -v -m user.dpc22 user.dpc22.zzz
Replication action on two MAILBOX objects:
S: MAILBOXES user.dpc22 user.dpc22.zzz
Ask server for contents of the two folders:
S: USER_SOME dpc22 ...
Reserve message with given GUID in user.dpc22 so that it can be moved
S: RESERVE user.dpc22 ...
Remove message from source folder (reserved copy left behind)
S: SELECT user.dpc22
S: EXPUNGE [1 msgs]
S: SETSEEN dpc22 ...
Create target folder and copy in message that we reserved (doesn't have to
be uploaded again)
S: CREATE user.dpc22.zzz 7f6f384c3f5ba99a
S: "dpc22 lrswipcda anonymous 0 " 0 1062971802
S: SELECT user.dpc22.zzz
S: UPLOAD [1 msgs]
S: SETSEEN dpc22 ...
S: ENDUSER
</pre></div>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="prot.html" class="btn btn-neutral float-left" title="Cyrus IMAP Server: prot layer" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="replication_protocol.html" class="btn btn-neutral float-right" title="Cyrus IMAP Server: Replication Protocol v2.4+" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1993–2025, The Cyrus Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
