1SYNC_CLIENT(8) Cyrus IMAP SYNC_CLIENT(8)
2
6 sync_client - Cyrus IMAP documentation
7 Client side of the synchronization (replication) engine
9
11 sync_client [ -v ] [ -l ] [ -L ] [ -z ] [ -C config-file ] [ -S server-name ]
12 [ -f input-file ] [ -F shutdown_file ] [ -w wait_interval ]
13 [ -t timeout ] [ -d delay ] [ -r ] [ -n channel ] [ -u ] [ -m ]
14 [ -p partition ] [ -A ] [ -N ] [ -s ] [ -O ] objects...
15
17 sync_client is the client side of the replication system. It runs on
18 the client (master) system and connects to the target (replica) system
19 and generates an appropriate sequence of transactions to synchronize
20 the replica system with the master system.
21 sync_client reads its configuration options out of the imapd.conf(5)
23 file unless specified otherwise by -C.
24
26 -C config-file
27 Use the specified configuration file config-file rather than the
28 default imapd.conf(5).
29 -A, --all-users
31 All users mode. Sync every user on the server to the replica
32 (doesn't do non-user mailboxes at all... this could be consid‐
33 ered a bug and maybe it should do those mailboxes independently)
34 -d delay, --delay=delay
36 Minimum delay between replication runs in rolling replication
37 mode. Larger values provide better efficiency as transactions
38 can be merged. Smaller values mean that the replica system is
39 more up to date and that you don't end up with large blocks of
40 replication transactions as a single group. Default: 3 seconds.
41 -f input-file, --input-file=input-file
43 In mailbox or user replication mode: provides list of users or
44 mailboxes to replicate. In rolling replication mode, specifies
45 an alternate log file (sync_client will exit after processing
46 the log file).
47 -F shutdown-file, --shutdown-file=shutdown-file
49 Rolling replication checks for this file at the end of each
50 replication cycle and shuts down if it is present. Used to re‐
51 quest a nice clean shutdown at the first convenient point. The
52 file is removed on shutdown. Overrides sync_shutdown_file option
53 in imapd.conf(5).
54 -l, --verbose-logging
56 Verbose logging mode.
57 -L, --local-only
59 Perform only local mailbox operations (do not do mupdate opera‐
60 tions). This feature was introduced in version 3.0.
61 -m, --mailboxes
63 Mailbox mode. Remaining arguments are list of mailboxes which
64 should be replicated.
65 -n channel, --channel=channel
67 Use the named channel for rolling replication mode. If multiple
68 channels are specified in sync_log_channels then use one of
69 them. This option is probably best combined with -S to connect
70 to a different server with each channel.
71 -N, --skip-locked
73 Use non-blocking sync_lock (combination of IP address and user‐
74 name) to skip over any users who are currently syncing.
75 -o, --connect-once
77 Only attempt to connect to the backend server once rather than
78 waiting up to 1000 seconds before giving up.
79 -O, --no-copyback
81 No copyback mode. Replication will stop if the replica reports a
82 CRC error, rather than doing a full mailbox sync. Useful if mov‐
83 ing users to a new server, where you don't want any errors to
84 cause the source servers to change the account.
85 -p partition, --dest-partition=partition
87 In mailbox or user replication mode: provides the name of the
88 partition on the replica to which the mailboxes/users should be
89 replicated.
90 -r, --rolling
92 Rolling (repeat) replication mode. Pick up a list of actions
93 recorded by the lmtpd(8), imapd(8), pop3d(8) and nntpd(8) dae‐
94 mons from the file specified in sync_log_file. Repeat until
95 sync_shutdown_file appears. Alternative log and shutdown files
96 can be specified with -f and -F.
97 In this invocation, sync_client will background itself to run as
99 a daemon.
100 -R, --foreground-rolling
102 As for -r, but without backgrounding.
103 -1, --rolling-once
105 As for -R, but only process a single log file before exiting.
106 -s, --sieve-mode
108 Sieve mode. Remaining arguments are list of users whose Sieve
109 files should be replicated. Principally used for debugging pur‐
110 poses: not exposed to sync_client(8).
111 -S servername, --server=servername
113 Tells sync_client with which server to communicate. Overrides
114 the sync_host configuration option.
115 -t timeout, --timeout=timeout
117 Timeout for single replication run in rolling replication.
118 sync_client will negotiate a restart after this many seconds.
119 Default: 600 seconds
120 -u, --userids
122 User mode. Remaining arguments are list of users who should be
123 replicated.
124 -v, --verbose
126 Verbose mode. Use twice (-v -v) to log all protocol traffic to
127 stderr.
128 -w interval, --delayed-startup=interval
130 Wait this long before starting. This option is typically used so
131 that we can attach a debugger to one end of the replication sys‐
132 tem or the other.
133 -z, --require-compression
135 Require compression. The replication protocol will always try
136 to enable deflate compression if both ends support it. Set this
137 flag when you want to abort if compression is not available.
138 -a, --stage-to-archive
140 Request the stage-to-archive feature. If the remote end has the
141 archive_enabled option set, then it will stage incoming replica‐
142 tion on the archive partition instead of the spool partition. If
143 the remote end does not support it, replication will proceed as
144 though -a was not provided. This option is useful when standing
145 up a new replica of an existing server, as most of the stored
146 mail is likely older than the archive threshold and so is des‐
147 tined for the archive partition anyway. By staging on that par‐
148 tition, Cyrus can avoid a cross-partition copy for every mes‐
149 sage.
150
152 On a replication master, the following would be added to the START sec‐
153 tion of cyrus.conf(5):
154 syncclient cmd="/usr/lib/cyrus/bin/sync_client -r"
156 [NB: More examples needed]
158
160 The -L feature, local updates only, was added in version 3.0.
161
163 /etc/imapd.conf
164
166 sync_server(8), cyrus.conf(5), imapd.conf(5), master(8)
167
169 The Cyrus Team, David Carter (dpc22@cam.ac.uk), Ken Murchison
170 (ken@oceana.com), Nic Bernstein (Onlight)
171
173 1993–2023, The Cyrus Team
1743.8.1 Sep 11, 2023 SYNC_CLIENT(8)