| 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)` |