# sync_client

Client side of the synchronization (replication) engine

## Synopsis

    sync_client [ -v ] [ -l ] [ -L ] [ -z ] [ -C config-file ] [ -S server-name ]
        [ -f input-file ] [ -F shutdown_file ] [ -w wait_interval ]
        [ -t timeout ] [ -d delay ] [ -r ] [ -n channel ] [ -u ] [ -m ]
        [ -p partition ] [ -A ] [ -N ] [ -s ] [ -O ] objects...

## Description

sync_client is the client side of the replication system. It runs on the client (master) system and connects to the target (replica) system and generates an appropriate sequence of transactions to synchronize the replica system with the master system.

sync_client reads its configuration options out of the imapd.conf(5) file unless specified otherwise by -C.

## Options

-C config-file

  Use the specified configuration file config-file rather than the default imapd.conf(5).

-A, --all-users

  All users mode. Sync every user on the server to the replica (doesn't do non-user mailboxes at all... this could be considered a bug and maybe it should do those mailboxes independently)

-d delay, --delay=delay

  Minimum delay between replication runs in rolling replication mode. Larger values provide better efficiency as transactions can be merged. Smaller values mean that the replica system is more up to date and that you don't end up with large blocks of replication transactions as a single group. Default: 3 seconds.

-f input-file, --input-file=input-file

  In mailbox or user replication mode: provides list of users or mailboxes to replicate. In rolling replication mode, specifies an alternate log file (sync_client will exit after processing the log file).

-F shutdown-file, --shutdown-file=shutdown-file

  Rolling replication checks for this file at the end of each replication cycle and shuts down if it is present. Used to request a nice clean shutdown at the first convenient point. The file is removed on shutdown. Overrides `sync_shutdown_file` option in imapd.conf(5).

-l, --verbose-logging

  Verbose logging mode.

-L, --local-only

  Perform only local mailbox operations (do not do mupdate operations). This feature was introduced in version 3.0.

-m, --mailboxes

  Mailbox mode. Remaining arguments are list of mailboxes which should be replicated.

-n channel, --channel=channel

  Use the named channel for rolling replication mode. If multiple channels are specified in `sync_log_channels` then use one of them. This option is probably best combined with -S to connect to a different server with each channel.

-N, --skip-locked

  Use non-blocking sync_lock (combination of IP address and username) to skip over any users who are currently syncing.

-o, --connect-once

  Only attempt to connect to the backend server once.

  Without this option, sync_client will retry failed connections indefinitely, waiting up to `sync_reconnect_maxwait` (default: 20m) between attempts.

-O, --no-copyback

  No copyback mode. Replication will stop if the replica reports a CRC error, rather than doing a full mailbox sync. Useful if moving users to a new server, where you don't want any errors to cause the source servers to change the account.

-p partition, --dest-partition=partition

  In mailbox or user replication mode: provides the name of the partition on the replica to which the mailboxes/users should be replicated.

-r, --rolling

  Rolling (repeat) replication mode. Pick up a list of actions recorded by the lmtpd(8), imapd(8), pop3d(8) and nntpd(8) daemons from the file specified in `sync_log_file`. Repeat until `sync_shutdown_file` appears. Alternative log and shutdown files can be specified with -f and -F.

  In this invocation, sync_client will background itself to run as a daemon.

-R, --foreground-rolling

  As for -r, but without backgrounding.

-1, --rolling-once

  As for -R, but only process a single log file before exiting.

-s, --sieve-mode

  Sieve mode. Remaining arguments are list of users whose Sieve files should be replicated. Principally used for debugging purposes: not exposed to sync_client(8).

-S servername, --server=servername

  Tells sync_client with which server to communicate. Overrides the `sync_host` configuration option.

-t timeout, --timeout=timeout

  Timeout for single replication run in rolling replication. sync_client will negotiate a restart after this many seconds. Default: 600 seconds

-u, --userids

  User mode. Remaining arguments are list of users who should be replicated.

-v, --verbose

  Verbose mode. Use twice (-v -v) to log all protocol traffic to stderr.

-w interval, --delayed-startup=interval

  Wait this long before starting. This option is typically used so that we can attach a debugger to one end of the replication system or the other.

-z, --require-compression

  Require compression. The replication protocol will always try to enable deflate compression if both ends support it. Set this flag when you want to abort if compression is not available.

-a, --stage-to-archive

  Request the stage-to-archive feature. If the remote end has the `archive_enabled` option set, then it will stage incoming replication on the archive partition instead of the spool partition. If the remote end does not support it, replication will proceed as though -a was not provided. This option is useful when standing up a new replica of an existing server, as most of the stored mail is likely older than the archive threshold and so is destined for the archive partition anyway. By staging on that partition, Cyrus can avoid a cross-partition copy for every message.

## Examples

On a replication master, the following would be added to the START section of cyrus.conf(5):

>     syncclient              cmd="/usr/lib/cyrus/bin/sync_client -r"

[NB: More examples needed]

## History

The -L feature, local updates only, was added in version 3.0.

## Files

/etc/imapd.conf

## See Also

sync_server(8), cyrus.conf(5), imapd.conf(5), master(8)