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
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
|
<!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>Replication: Installation and Administration — Cyrus IMAP 3.10.2 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="Mailbox Operations" href="mailbox-operations.html" />
<link rel="prev" title="Standard Operating Procedures" href="../sop.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.10.2
</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 current"><a class="reference internal" href="../../../../operations.html">Operations</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../manpages/index.html">Man pages</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../admin.html">Administrator Guide</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../../admin.html#architecture">Architecture</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../../admin.html#management">Management</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="../locations.html">File & Directory Locations</a></li>
<li class="toctree-l4"><a class="reference internal" href="../ports-sockets.html">Ports and Sockets</a></li>
<li class="toctree-l4"><a class="reference internal" href="../access-control.html">Access Control</a></li>
<li class="toctree-l4"><a class="reference internal" href="../quotas.html">Quotas</a></li>
<li class="toctree-l4"><a class="reference internal" href="../sieve.html">Cyrus Sieve</a></li>
<li class="toctree-l4"><a class="reference internal" href="../backups.html">Cyrus Backups</a></li>
<li class="toctree-l4"><a class="reference internal" href="../nntp.html">Cyrus NNTP</a></li>
<li class="toctree-l4"><a class="reference internal" href="../protlayer.html">Cyrus Prot Layer</a></li>
<li class="toctree-l4 current"><a class="reference internal" href="../sop.html">Standard Operating Procedures</a></li>
<li class="toctree-l4"><a class="reference internal" href="../eventsource.html">Cyrus Event Source</a></li>
<li class="toctree-l4"><a class="reference internal" href="../monitoring.html">Monitoring</a></li>
<li class="toctree-l4"><a class="reference internal" href="../config-mailboxdistribution.html">Mailbox Distribution</a></li>
<li class="toctree-l4"><a class="reference internal" href="../murder/murder.html">Cyrus Murder</a></li>
<li class="toctree-l4"><a class="reference internal" href="../nginx-proxy.html">HOWTO: Using an NGINX IMAP Proxy</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tweaking.html">Tweaking Cyrus IMAP</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../faq.html">Frequently Asked Questions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../../developers.html">Developers</a></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="../../../../operations.html">Operations</a></li>
<li class="breadcrumb-item"><a href="../../admin.html">Administrator Guide</a></li>
<li class="breadcrumb-item"><a href="../sop.html">Standard Operating Procedures</a></li>
<li class="breadcrumb-item active">Replication: Installation and Administration</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/reference/admin/sop/replication.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">
<section id="replication-installation-and-administration">
<span id="replication"></span><h1>Replication: Installation and Administration<a class="headerlink" href="#replication-installation-and-administration" title="Permalink to this heading"></a></h1>
<section id="architecture">
<h2>Architecture<a class="headerlink" href="#architecture" title="Permalink to this heading"></a></h2>
<p><a class="reference internal" href="../../architecture.html#architecture-replication"><span class="std std-ref">Overall structure of replication</span></a>.</p>
</section>
<section id="terminology">
<h2>Terminology<a class="headerlink" href="#terminology" title="Permalink to this heading"></a></h2>
<dl class="simple">
<dt>Host</dt><dd><p>A computer chassis, slot or cabinet. A machine.</p>
</dd>
<dt>Server or Service</dt><dd><p>A program or process which "serves" a particular protocol.
Typically a server will listen on a network port or Unix socket
for communications from a client (local or remote).</p>
</dd>
<dt>Client</dt><dd><p>A program or process which talks to a server or servers for a given
protocol. The initiator of a client/server session.</p>
</dd>
<dt>Instance</dt><dd><p>A particular instance or iteration of a program, which may be one,
or one of many, providing similar services to different consumers.</p>
</dd>
<dt>Master</dt><dd><p>In this document, Master always means the source of data to be
replicated.</p>
</dd>
<dt>Replica</dt><dd><p>The target of data replication is the Replica, which refers both to
an instance of sync_server and to the resultant dataset.</p>
</dd>
</dl>
</section>
<section id="operating-modes">
<h2>Operating Modes<a class="headerlink" href="#operating-modes" title="Permalink to this heading"></a></h2>
<p>Cyrus replication supports two modes of operation: Rolling and
Periodic. The difference is that rolling replication is a more or less
continuous process whereas periodic replication occurs on demand,
triggered by some manual or automated process such as
<em class="manpage">cron(8)</em>.</p>
<section id="rolling-replication">
<h3>Rolling Replication<a class="headerlink" href="#rolling-replication" title="Permalink to this heading"></a></h3>
<p>Rolling replication is enabled by setting <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> to True in
<a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>. With <code class="docutils literal notranslate"><span class="pre">sync_log:</span> <span class="pre">true</span></code>, any process which
alters the mail spool will update the <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> files with details
as to which mailbox(es) or users have been affected by their actions.
In this way the <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> acts as a command file for the
<a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> process(es).</p>
<p>The log files are stored in <code class="docutils literal notranslate"><span class="pre">{configdirectory}/sync/log</span></code> for single
channel systems (see <a class="reference internal" href="#replication-channels"><span class="std std-ref">Channels</span></a> for more information)
and are rotated on a regular basis by Cyrus. Multi-channel deployments
will have a separate <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> file for each, stored as
<code class="docutils literal notranslate"><span class="pre">{configdirectory}/sync/<channel>/log</span></code>.</p>
<p>Upon completing a log file, <code class="docutils literal notranslate"><span class="pre">sync_client</span></code> will go to sleep, or, if
processing took longer than <code class="docutils literal notranslate"><span class="pre">sync_repeat_interval</span></code> seconds, will
start over again on the next log.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Any unsuccessful run of sync_client will result in the incomplete
remains of the original log file being left behind as "log-<$PID>".
This may be re-run as needed.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Please also see <a class="reference internal" href="#replication-other-uses"><span class="std std-ref">below for other uses of sync_log</span></a>.</p>
</div>
</section>
<section id="periodic-replication">
<h3>Periodic Replication<a class="headerlink" href="#periodic-replication" title="Permalink to this heading"></a></h3>
<p>With <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> set to the default False, replication must be
triggered either by manually running <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a>, or by
doing so via <code class="docutils literal notranslate"><span class="pre">cron</span></code> or an entry in <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a>.</p>
<p>In either event, command line switches control the operation of
<code class="docutils literal notranslate"><span class="pre">sync_client</span></code>.</p>
<p>Once the process completes its work, it will exit.</p>
</section>
<section id="idempotency">
<h3>Idempotency<a class="headerlink" href="#idempotency" title="Permalink to this heading"></a></h3>
<p>Synchronization itself is idempotent in either mode, so log files may
be "replayed" without concern of damage to the replica's mail spools.</p>
</section>
<section id="sync-chains">
<h3>Sync Chains<a class="headerlink" href="#sync-chains" title="Permalink to this heading"></a></h3>
<p>Cyrus supports chained replication, in which one replica replicates to
another. I.e. A replicates to B; B replicates to C. If you wish to
use this approach, please see the <code class="docutils literal notranslate"><span class="pre">sync_log_chain</span></code> setting:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">sync_log_chain:</span></code> 0</p>
<blockquote>
<div><p>Enable replication action logging by sync_server as well, allowing
chaining of replicas. Use this on 'B' for A => B => C replication layout.</p>
</div></blockquote>
</div></blockquote>
<p>Note that sync_log_chain is to be set on the middle server(s) in a
chain, not on the first or last.</p>
</section>
</section>
<section id="transport">
<h2>Transport<a class="headerlink" href="#transport" title="Permalink to this heading"></a></h2>
<p>Older versions (pre-3.0) of Cyrus used the dedicated <code class="docutils literal notranslate"><span class="pre">csync</span></code>
transport -- typically over TCP port 2005 -- and server process --
<a class="reference internal" href="../../manpages/systemcommands/sync_server.html#std-cyrusman-sync_server-8">sync_server(8)</a> -- for replication. This is no longer
necessary.</p>
<p>From v3.0 forward, the <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> will default to using
IMAP protocol for transport, and an IMAP instance on the replica will
process the synchronization instructions. If you wish, you may
override this by setting the <code class="docutils literal notranslate"><span class="pre">sync_try_imap</span></code> setting in
<a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> to False.</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">sync_try_imap:</span></code> 1</p>
<blockquote>
<div><p>Whether sync_client should try to perform an IMAP connection
before falling back to csync. If this is set to "no",
sync_client will only use csync. Prefix with a channel name to
apply only for that channel.</p>
</div></blockquote>
</div></blockquote>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h2>
<p>One must <a class="reference internal" href="../../../developer/compiling.html#compiling"><span class="std std-ref">build Cyrus IMAPd</span></a> with the
<code class="docutils literal notranslate"><span class="pre">--enable-replication</span></code> configure option. This builds the replication
client/server applications and utilities.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Those using their distribution's packages may need to install a
separate package for replication support. For example, on Debian
and derived distros, install the <code class="docutils literal notranslate"><span class="pre">cyrus-replication</span></code> package.</p>
</div>
<section id="requirements">
<h3>Requirements<a class="headerlink" href="#requirements" title="Permalink to this heading"></a></h3>
<ol class="arabic simple">
<li><p>At least one Cyrus IMAP server instance to be the <strong>master</strong>.</p></li>
<li><p>At least one Cyrus IMAP server instance to be the <strong>replica</strong>.</p></li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Sample configurations for both "master" and "replica" instances are
included in the standard distribution.</p>
</div>
</section>
<section id="replica-server-configuration">
<h3>Replica server configuration<a class="headerlink" href="#replica-server-configuration" title="Permalink to this heading"></a></h3>
<p>The <strong>replica</strong> is a standalone server instance which listens for and
processes synchronization messages from a single <strong>master</strong> server. The
replica server needs to be configured to accept synchronization
messages via IMAP or the (deprecated) <a class="reference internal" href="../../manpages/systemcommands/sync_server.html#std-cyrusman-sync_server-8">sync_server(8)</a>
process.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Within a Cyrus <a class="reference internal" href="../../architecture.html#architecture-murder"><span class="std std-ref">Murder</span></a> environment,
replicas must <strong>not</strong> be configured to invoke
<a class="reference internal" href="../../manpages/systemcommands/ctl_mboxlist.html#std-cyrusman-ctl_mboxlist-8">ctl_mboxlist(8)</a> on startup (pushing the local mailbox
list to the <strong>Mupdate Master</strong>). This may only be done on the
Master instance.</p>
</div>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>It is critically important that all partitions existing on a master
server instance also be present on all replica instances. Failure
to ensure this will result in crashes and could lead to lost data
on the replicas.</p>
</div>
<ol class="arabic">
<li><p><a class="reference internal" href="../../../installing.html#installing"><span class="std std-ref">Configure a standalone server</span></a>.</p></li>
<li><p>If using the deprecated sync_server scheme, add the following line
to the <code class="docutils literal notranslate"><span class="pre">/etc/services</span></code> file. Note that the port number is
arbitrary as long as its not being used by any other services on the
network.</p>
<blockquote>
<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">csync</span> <span class="mi">2005</span><span class="o">/</span><span class="n">tcp</span>
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>If using the deprecated sync_server scheme, add a line similar to
the following in the SERVICES section of <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a>:</p>
<blockquote>
<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syncserver</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_server"</span> <span class="n">listen</span><span class="o">=</span><span class="s2">"csync"</span>
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Start/restart <code class="docutils literal notranslate"><span class="pre">/usr/cyrus/bin/master</span></code>.</p></li>
</ol>
</section>
<section id="master-server-configuration">
<h3>Master server configuration<a class="headerlink" href="#master-server-configuration" title="Permalink to this heading"></a></h3>
<p>The <strong>master</strong> server is a standalone or backend Cyrus IMAP server
instance which is actively serving mailboxes to clients. This server
needs to be configured to synchronize its mailstore with a <strong>replica</strong>
server via an instance of <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a>.</p>
<p>If using the deprecated sync_server scheme, add the following line to
the <code class="docutils literal notranslate"><span class="pre">/etc/services</span></code> file.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">csync</span> <span class="mi">2005</span><span class="o">/</span><span class="n">tcp</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The port number <strong>MUST</strong> be the same as that used on the replica
server.</p>
</div>
<p>Specify the hostname of the replica server and how to authenticate to
it in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> using these options:</p>
<blockquote>
<div><ul class="simple">
<li><p>sync_host</p></li>
<li><p>sync_port</p></li>
<li><p>sync_authname</p></li>
<li><p>sync_realm</p></li>
<li><p>sync_password</p></li>
</ul>
</div></blockquote>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">sync_authname</span></code> <strong>MUST</strong> be an <code class="docutils literal notranslate"><span class="pre">admin</span></code> user on the replica.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">sync_realm</span></code> and <code class="docutils literal notranslate"><span class="pre">sync_password</span></code> may not be necessary
depending on the SASL mechanism used for authentication.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>See <a class="reference internal" href="#replication-channels"><span class="std std-ref">Channels</span></a>, below, for details on how to use
these settings to control syncing to multiple replicas.</p>
</div>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>If using sync_log_channels for any other purpose, such as
specifying the sync_log used by <a class="reference internal" href="../../manpages/systemcommands/squatter.html#std-cyrusman-squatter-8">squatter(8)</a> command,
you must <em>also</em> either specify a sync_log channel for replication,
or specify the default "" (the two-character string U+22 U+22).</p>
</div>
<p>Add invocation specifications to <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a> to spawn
<a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> as desired (for each channel used) as
described below in Rolling Replication or Periodic Replication.</p>
</section>
<section id="compression">
<h3>Compression<a class="headerlink" href="#compression" title="Permalink to this heading"></a></h3>
<p>If one runs replication over a WAN link, the trade-off between
bandwidth and CPU usage will tilt strongly in favour of enabling
compression to save bandwidth at a slight increase in CPU cost. Set
the <code class="docutils literal notranslate"><span class="pre">sync_compress</span></code> value in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_compress</span><span class="p">:</span> <span class="n">On</span>
</pre></div>
</div>
<p>or pass the <code class="docutils literal notranslate"><span class="pre">-z</span></code> flag to <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> in the service
spec in <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r -z"</span>
</pre></div>
</div>
</section>
<section id="rolling-replication-configuration">
<h3>Rolling Replication Configuration<a class="headerlink" href="#rolling-replication-configuration" title="Permalink to this heading"></a></h3>
<p><strong>Rolling Replication</strong> means that the master instance continuously
synchronizes itself with a replica.</p>
<p>To configure rolling replication, perform the following:</p>
<ol class="arabic">
<li><p>Enable the <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> option in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>. This
allows the imapd, pop3d, nntpd, and lmtpd services to log
synchronization actions which will be periodically serviced by
sync_client:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_log</span><span class="p">:</span> <span class="n">On</span>
</pre></div>
</div>
</li>
<li><p>Optionally, adjust the <code class="docutils literal notranslate"><span class="pre">sync_repeat_interval</span></code> in
<a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_repeat_interval</span><span class="p">:</span> <span class="mi">300</span>
</pre></div>
</div>
</li>
<li><p>Add a line similar to the following in the STARTUP section of
<a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r"</span>
</pre></div>
</div>
</li>
</ol>
<p>Start/restart <code class="docutils literal notranslate"><span class="pre">/usr/cyrus/bin/master</span></code>.</p>
<div class="admonition hint">
<p class="admonition-title">Hint</p>
<p>In a multi-channel mesh, the channel to be used by a given
sync_client must be specified via the "-n <channel>" argument on
the command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r -n channel1"</span>
</pre></div>
</div>
</div>
</section>
<section id="terminating-rolling-replication">
<h3>Terminating Rolling Replication<a class="headerlink" href="#terminating-rolling-replication" title="Permalink to this heading"></a></h3>
<p>To be able to stop rolling replication at any time, configure the
<code class="docutils literal notranslate"><span class="pre">sync_shutdown_file</span></code> option in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> to point to
a non-existant file, the appearance of this file will trigger a
shutdown of a <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_shutdown_file</span><span class="p">:</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">imap</span><span class="o">/</span><span class="n">syncstop</span>
</pre></div>
</div>
</section>
<section id="tweaking-rolling-replication">
<h3>Tweaking Rolling Replication<a class="headerlink" href="#tweaking-rolling-replication" title="Permalink to this heading"></a></h3>
<p>The default frequency of replication runs is 3 seconds. Lengthening
this produces higher efficiency at the cost of slightly more stale data
on the replica. Alter this via the sync_repeat_interval in
<a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> or by using the "-d" argument in the
invocation of <a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a>.</p>
</section>
<section id="periodic-replication-configuration">
<h3>Periodic Replication Configuration<a class="headerlink" href="#periodic-replication-configuration" title="Permalink to this heading"></a></h3>
<p>In Periodic Replication the sync_client instance must be spawned
from time to time, causing replication to start at that time. This may
be handled via a <em class="manpage">cron(8)</em> job, or by adding an entry to the
EVENTS section of <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a> like any of these:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EVENTS</span> <span class="p">{</span>
<span class="o"><...></span>
<span class="c1"># Periodically sync ALL user mailboxes every 4 hours</span>
<span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -A"</span> <span class="n">period</span><span class="o">=</span><span class="mi">240</span>
<span class="c1"># Periodically sync changes at specific times</span>
<span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -A"</span> <span class="n">at</span><span class="o">=</span><span class="mi">0800</span>
<span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -A"</span> <span class="n">at</span><span class="o">=</span><span class="mi">1200</span>
<span class="n">syncclient</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -A"</span> <span class="n">at</span><span class="o">=</span><span class="mi">1800</span>
<span class="o"><...></span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When using the "-A" flag (sync all users) no non-user
mailboxes are synced. As the man page <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>
notes, "... this could be considered a bug and maybe it should do
those mailboxes independently."</p>
</div>
</section>
<section id="tweaking-replication">
<h3>Tweaking Replication<a class="headerlink" href="#tweaking-replication" title="Permalink to this heading"></a></h3>
<p>You may control the number of messages replicated in each batch, via
the <code class="docutils literal notranslate"><span class="pre">sync_batchsize</span></code> setting:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">sync_batchsize:</span></code> 8192</p>
<blockquote>
<div><p>the number of messages to upload in a single mailbox replication.
Default is 8192. If there are more than this many messages appended
to the mailbox, generate a synthetic partial state and send that.</p>
</div></blockquote>
</div></blockquote>
</section>
</section>
<section id="channels">
<span id="replication-channels"></span><h2>Channels<a class="headerlink" href="#channels" title="Permalink to this heading"></a></h2>
<p>The Cyrus replication scheme is very flexible, and supports meshes in
which masters running on various hosts may replicate to instances on
other hosts. This is achieved by use of the Channels feature of the
replication system.</p>
<p>To employ channels, prefix any of the following sync_ configuration
options in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> with the channel name and an
underscore "_" character as needed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_authname</span>
<span class="n">sync_password</span>
<span class="n">sync_realm</span>
<span class="n">sync_host</span>
<span class="n">sync_port</span>
<span class="n">sync_repeat_interval</span>
<span class="n">sync_shutdown_file</span>
</pre></div>
</div>
<p>Then add the setting <code class="docutils literal notranslate"><span class="pre">sync_log_channels</span></code> with a list of the channels:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_log_channels</span><span class="p">:</span> <span class="n">chan1</span> <span class="n">chan2</span> <span class="n">chan3</span>
</pre></div>
</div>
<p>For example, a site using the same auth credentials for all servers has
no need to specify unique per-channel settings for <code class="docutils literal notranslate"><span class="pre">sync_authname</span></code>,
<code class="docutils literal notranslate"><span class="pre">sync_password</span></code> or <code class="docutils literal notranslate"><span class="pre">sync_realm</span></code>, but might do the following for the
rest of the sync related settings in <a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sync_authname</span><span class="p">:</span> <span class="n">replman</span>
<span class="n">sync_password</span><span class="p">:</span> <span class="o"><</span><span class="n">secret</span><span class="o">></span>
<span class="n">sync_log_channels</span><span class="p">:</span> <span class="n">repl1</span> <span class="n">repl2</span> <span class="n">offsite</span>
<span class="c1">##</span>
<span class="c1"># The main replica</span>
<span class="n">repl1_sync_host</span><span class="p">:</span> <span class="n">mailrepl1</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">org</span>
<span class="n">repl1_sync_repeat_interval</span><span class="p">:</span> <span class="mi">180</span>
<span class="n">repl1_shutdown_file</span><span class="p">:</span> <span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">cyrus</span><span class="o">/</span><span class="n">sync</span><span class="o">/</span><span class="n">repl1_shutdown</span>
<span class="c1">##</span>
<span class="c1"># A second replica used to feed the tape backup system</span>
<span class="n">repl2_sync_host</span><span class="p">:</span> <span class="n">mailrepl2</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">org</span>
<span class="n">repl2_sync_repeat_interval</span><span class="p">:</span> <span class="mi">180</span>
<span class="n">repl2_shutdown_file</span><span class="p">:</span> <span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">cyrus</span><span class="o">/</span><span class="n">sync</span><span class="o">/</span><span class="n">repl2_shutdown</span>
<span class="c1">##</span>
<span class="c1"># An offsite replica which needs a different port and uses a slower</span>
<span class="c1"># cycle rate</span>
<span class="n">offsite_sync_port</span><span class="p">:</span> <span class="mi">19205</span>
<span class="n">offsite_sync_host</span><span class="p">:</span> <span class="n">mailoffsite</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">org</span>
<span class="n">offsite_sync_repeat_interval</span><span class="p">:</span> <span class="mi">360</span>
<span class="n">offsite_shutdown_file</span><span class="p">:</span> <span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">cyrus</span><span class="o">/</span><span class="n">sync</span><span class="o">/</span><span class="n">offsite_shutdown</span>
</pre></div>
</div>
<p>Then these entries in <a class="reference internal" href="../../manpages/configs/cyrus.conf.html#std-cyrusman-cyrus.conf-5">cyrus.conf(5)</a> would complete the
exercise:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">repl1sync</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r -n repl1"</span>
<span class="n">repl2sync</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r -n repl2"</span>
<span class="n">offsitesync</span> <span class="n">cmd</span><span class="o">=</span><span class="s2">"/usr/cyrus/bin/sync_client -r -n offsite"</span>
</pre></div>
</div>
<p>Again, this is just an example for illustration. The system provides so
much flexibility, and one can combine channels with chaining to achieve
even more.</p>
</section>
<section id="other-considerations">
<span id="replication-other-uses"></span><h2>Other Considerations<a class="headerlink" href="#other-considerations" title="Permalink to this heading"></a></h2>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This section is currently under development. If you believe you
are impacted by these considerations, please check back with each
release and follow the mailing list.</p>
</div>
<p>The infrastructure provided by <code class="docutils literal notranslate"><span class="pre">sync_log</span></code> has now been leveraged by
the Rolling Indexing capability introduced in v3.0. See
<a class="reference internal" href="../../manpages/systemcommands/squatter.html#std-cyrusman-squatter-8">squatter(8)</a> for more details (see the fourth mode synopsis).</p>
<p>Specifically, the following new settings have been added to
<a class="reference internal" href="../../manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> in support of this new use of <code class="docutils literal notranslate"><span class="pre">sync_log</span></code>:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">sync_log_unsuppressable_channels:</span></code> squatter</p>
<blockquote>
<div><p>If specified, the named channels are exempt from the effect of setting
sync_log_chain:off, i.e. they are always logged to by the sync_server
process. This is only really useful to allow rolling search indexing
on a replica.</p>
</div></blockquote>
</div></blockquote>
</section>
<section id="administration">
<h2>Administration<a class="headerlink" href="#administration" title="Permalink to this heading"></a></h2>
<section id="manual-replication">
<h3>Manual replication<a class="headerlink" href="#manual-replication" title="Permalink to this heading"></a></h3>
<p>To manually synchronize any part of the mailstore, run
<a class="reference internal" href="../../manpages/systemcommands/sync_client.html#std-cyrusman-sync_client-8">sync_client(8)</a> with the appropriate command line options.
Note that manual synchronization DOES NOT interfere with rolling
replication.</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">root</span><span class="nd">@skynet</span> <span class="o">~</span><span class="p">]</span><span class="c1"># /usr/lib/cyrus-imapd/sync_client -S cyrus-replica.example.org -v -u john.doe@example.org</span>
<span class="n">USER</span> <span class="n">john</span><span class="o">^</span><span class="n">doe</span><span class="nd">@example</span><span class="o">.</span><span class="n">org</span>
</pre></div>
</div>
<p>One can run <a class="reference internal" href="../../manpages/systemcommands/cyr_synclog.html#std-cyrusman-cyr_synclog-8">cyr_synclog(8)</a> instead, which will insert the
record into the rolling replication log.</p>
</section>
<section id="failover">
<h3>Failover<a class="headerlink" href="#failover" title="Permalink to this heading"></a></h3>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../sop.html" class="btn btn-neutral float-left" title="Standard Operating Procedures" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="mailbox-operations.html" class="btn btn-neutral float-right" title="Mailbox Operations" 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>
|
