---
name: "cyrus-sync_client"
section: "8"
platform: "linux"
package: "cyrus-replication"
version: "3.10.2-1+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cyrus-sync_client"
---

# cyrus-sync\_client(8)

Cyrus IMAP documentation Client side of the synchronization (replication) engine

## NAME

sync\_client - Cyrus IMAP documentation

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)](/imapd.conf/5.md) file unless specified otherwise by* **-C***.*

## OPTIONS

- **-C config-file**

  *Use the specified configuration file config-file rather than the default [imapd.conf(5)](/imapd.conf/5.md).*

- **-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)](/imapd.conf/5.md).*

- **-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)](/lmtpd/8.md), [imapd(8)](/imapd/8.md),* *[pop3d(8)](/pop3d/8.md) and [nntpd(8)](/nntpd/8.md) 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)](/sync_client/8.md).*

- **-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)](/cyrus.conf/5.md):*

```
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)](/sync_server/8.md), [cyrus.conf(5)](/cyrus.conf/5.md),* *[imapd.conf(5)](/imapd.conf/5.md), [master(8)](/master/8.md)*

## AUTHOR

*The Cyrus Team, David Carter (dpc22@cam.ac.uk), Ken Murchison (ken@oceana.com), Nic Bernstein (Onlight)*

## COPYRIGHT

*1993–2025, The Cyrus Team*