Debian Codegraph @

doc/html/_sources/imap/reference/manpages/systemcommands/sync_client.rst.txt

raw
1 .. cyrusman:: sync_client(8)
2
3 .. author: David Carter ([email protected])
4 .. author: Ken Murchison ([email protected])
5 .. author: Nic Bernstein (Onlight)
6
7 .. _imap-reference-manpages-systemcommands-sync_client:
8
9 ===============
10 **sync_client**
11 ===============
12
13 Client side of the synchronization (replication) engine
14
15 Synopsis
16 ========
17
18 .. parsed-literal::
19
20 **sync_client** [ **-v** ] [ **-l** ] [ **-L** ] [ **-z** ] [ **-C** *config-file* ] [ **-S** *server-name* ]
21 [ **-f** *input-file* ] [ **-F** *shutdown_file* ] [ **-w** *wait_interval* ]
22 [ **-t** *timeout* ] [ **-d** *delay* ] [ **-r** ] [ **-n** *channel* ] [ **-u** ] [ **-m** ]
23 [ **-p** *partition* ] [ **-A** ] [ **-N** ] [ **-s** ] [ **-O** ] *objects*...
24
25 Description
26 ===========
27
28 **sync_client** is the client side of the replication system. It runs
29 on the client (master) system and connects to the target (replica)
30 system and generates an appropriate sequence of transactions to
31 synchronize the replica system with the master system.
32
33 **sync_client** |default-conf-text|
34
35 Options
36 =======
37
38 .. program:: sync_client
39
40 .. option:: -C config-file
41
42 |cli-dash-c-text|
43
44 .. option:: -A, --all-users
45
46 All users mode.
47 Sync every user on the server to the replica (doesn't do non-user
48 mailboxes at all... this could be considered a bug and maybe it
49 should do those mailboxes independently)
50
51 .. option:: -d delay, --delay=delay
52
53 Minimum delay between replication runs in rolling replication mode.
54 Larger values provide better efficiency as transactions can be
55 merged. Smaller values mean that the replica system is more up to
56 date and that you don't end up with large blocks of replication
57 transactions as a single group. Default: 3 seconds.
58
59 .. option:: -f input-file, --input-file=input-file
60
61 In mailbox or user replication mode: provides list of users or
62 mailboxes to replicate. In rolling replication mode, specifies an
63 alternate log file (**sync_client** will exit after processing the
64 log file).
65
66 .. option:: -F shutdown-file, --shutdown-file=shutdown-file
67
68 Rolling replication checks for this file at the end of each
69 replication cycle and shuts down if it is present. Used to request
70 a nice clean shutdown at the first convenient point. The file is
71 removed on shutdown. Overrides ``sync_shutdown_file`` option in
72 :cyrusman:`imapd.conf(5)`.
73
74 .. option:: -l, --verbose-logging
75
76 Verbose logging mode.
77
78 .. option:: -L, --local-only
79
80 Perform only local mailbox operations (do not do mupdate operations).
81 |v3-new-feature|
82
83 .. option:: -m, --mailboxes
84
85 Mailbox mode.
86 Remaining arguments are list of mailboxes which should be replicated.
87
88 .. option:: -n channel, --channel=channel
89
90 Use the named channel for rolling replication mode. If multiple
91 channels are specified in ``sync_log_channels`` then use one of them.
92 This option is probably best combined with **-S** to connect to a
93 different server with each channel.
94
95 .. option:: -N, --skip-locked
96
97 Use non-blocking sync_lock (combination of IP address and username)
98 to skip over any users who are currently syncing.
99
100 .. option:: -o, --connect-once
101
102 Only attempt to connect to the backend server once.
103
104 Without this option, **sync_client** will retry failed connections
105 indefinitely, waiting up to ``sync_reconnect_maxwait`` (default: 20m)
106 between attempts.
107
108 .. option:: -O, --no-copyback
109
110 No copyback mode. Replication will stop if the replica reports a CRC
111 error, rather than doing a full mailbox sync. Useful if moving users to a
112 new server, where you don't want any errors to cause the source servers
113 to change the account.
114
115 .. option:: -p partition, --dest-partition=partition
116
117 In mailbox or user replication mode: provides the name of the
118 partition on the replica to which the mailboxes/users should be
119 replicated.
120
121 .. option:: -r, --rolling
122
123 Rolling (repeat) replication mode. Pick up a list of actions
124 recorded by the :cyrusman:`lmtpd(8)`, :cyrusman:`imapd(8)`,
125 :cyrusman:`pop3d(8)` and :cyrusman:`nntpd(8)` daemons from the file
126 specified in ``sync_log_file``. Repeat until ``sync_shutdown_file``
127 appears. Alternative log and shutdown files can be specified with
128 **-f** and **-F**.
129
130 In this invocation, sync_client will background itself to run as a
131 daemon.
132
133 .. option:: -R, --foreground-rolling
134
135 As for **-r**, but without backgrounding.
136
137 .. option:: -1, --rolling-once
138
139 As for **-R**, but only process a single log file before exiting.
140
141 .. option:: -s, --sieve-mode
142
143 Sieve mode.
144 Remaining arguments are list of users whose Sieve files should be
145 replicated. Principally used for debugging purposes: not exposed to
146 :cyrusman:`sync_client(8)`.
147
148 .. option:: -S servername, --server=servername
149
150 Tells **sync_client** with which server to communicate. Overrides
151 the ``sync_host`` configuration option.
152
153 .. option:: -t timeout, --timeout=timeout
154
155 Timeout for single replication run in rolling replication.
156 **sync_client** will negotiate a restart after this many seconds.
157 Default: 600 seconds
158
159 .. option:: -u, --userids
160
161 User mode.
162 Remaining arguments are list of users who should be replicated.
163
164 .. option:: -v, --verbose
165
166 Verbose mode. Use twice (**-v -v**) to log all protocol traffic to
167 stderr.
168
169 .. option:: -w interval, --delayed-startup=interval
170
171 Wait this long before starting. This option is typically used so
172 that we can attach a debugger to one end of the replication system
173 or the other.
174
175 .. option:: -z, --require-compression
176
177 Require compression.
178 The replication protocol will always try to enable deflate
179 compression if both ends support it. Set this flag when you want
180 to abort if compression is not available.
181
182 .. option:: -a, --stage-to-archive
183
184 Request the stage-to-archive feature. If the remote end has the
185 ``archive_enabled`` option set, then it will stage incoming replication on
186 the archive partition instead of the spool partition. If the remote end
187 does not support it, replication will proceed as though **-a** was not
188 provided. This option is useful when standing up a new replica of an
189 existing server, as most of the stored mail is likely older than the
190 archive threshold and so is destined for the archive partition anyway. By
191 staging on that partition, Cyrus can avoid a cross-partition copy for every
192 message.
193
194 Examples
195 ========
196
197 On a replication master, the following would be added to the START
198 section of :cyrusman:`cyrus.conf(5)`:
199
200 ::
201
202 syncclient cmd="/usr/lib/cyrus/bin/sync_client -r"
203
204 [NB: More examples needed]
205
206 History
207 =======
208
209 The **-L** feature, local updates only, was added in version 3.0.
210
211 Files
212 =====
213
214 * /etc/imapd.conf
215 * <configdirectory>/sync/skipuser-<user> - if file exists, user will not be
216 replicated
217 * <configdirectory>/sync/<channel>/skipuser-<user> - if file exists, user will
218 not be replicated for channel
219
220 See Also
221 ========
222
223 :cyrusman:`sync_server(8)`, :cyrusman:`cyrus.conf(5)`,
224 :cyrusman:`imapd.conf(5)`, :cyrusman:`master(8)`