SYNC_CLIENT(8)

📦
version 3.12.4 · 6 versions
, in fedora 44

💖 SYNC_CLIENT(8) 💖

okay bestie, welcome to SYNC_CLIENT, section 8 of the Cyrus IMAP docs. this is the client side of the replication (synchronization) engine, and honestly? she's the main character. let's get into it 🫶

✨ NAME ✨

sync_client — Cyrus IMAP documentation, and also the client side of the synchronization (replication) engine. yes, both things. iconic.

🌸 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...

look at all those little flags. she's got range 💅

🦋 DESCRIPTION 🦋

okay so sync_client is the client side of the replication system, no cap. she runs on the client (master) system, connects to the target (replica) system, and then generates a whole appropriate sequence of transactions to synchronize the replica system with the master system. literally doing the most, and we love her for it.

and listen — sync_client reads its configuration options out of the imapd.conf(5) file, unless you say otherwise with -C. that's it, that's the rule. 🎀

💅 OPTIONS 💅

  • -C config-file — use the specified configuration file config-file instead of the default imapd.conf(5). you're the boss, you pick the file.
  • -A, --all-users — All users mode. syncs every user on the server to the replica. and, um, heads up: it doesn't do non-user mailboxes at all... which could be considered a bug, and maybe it should do those mailboxes independently. so yeah, that's a thing. 🙈
  • -d delay, --delay=delay — minimum delay between replication runs in rolling replication mode. bigger values = better efficiency, because transactions can be merged. smaller values = the replica system is more up to date, and you don't end up with big blocks of replication transactions clumped into a single group. default: 3 seconds.
  • -f input-file, --input-file=input-file — in mailbox or user replication mode: provides the list of users or mailboxes to replicate. in rolling replication mode, it specifies an alternate log file — and sync_client will exit after processing that log file. bye bestie 👋
  • -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's present. it's how you request a nice, clean shutdown at the first convenient point. the file gets removed on shutdown. this overrides the sync_shutdown_file option in imapd.conf(5).
  • -l, --verbose-logging — verbose logging mode. she's chatty now. 🗣️
  • -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. the remaining arguments are the 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, so you connect to a different server with each channel. combo move ✨
  • -N, --skip-locked — use non-blocking sync_lock (that's a combination of IP address and username) to skip over any users who are currently syncing. not me interrupting, we'll come back. 💀
  • -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. she's persistent. she's patient. she's not giving up on you.

  • -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 you're moving users to a new server and you really don't want any errors causing the source servers to change the account. protect the source, periodt.
  • -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. picks 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. repeats 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. she's going to go be mysterious now.

  • -R, --foreground-rolling — as for -r, but without backgrounding. she stays right here where you can see her. 🫶
  • -1, --rolling-once — as for -R, but only process a single log file before exiting.
  • -s, --sieve-mode — Sieve mode. the remaining arguments are the list of users whose Sieve files should be replicated. principally used for debugging purposes: not exposed to sync_client(8). secret menu energy, iykyk.
  • -S servername, --server=servername — tells sync_client which server to communicate with. overrides the sync_host configuration option.
  • -t timeout, --timeout=timeout — timeout for a single replication run in rolling replication. sync_client will negotiate a restart after this many seconds. default: 600 seconds.
  • -u, --userids — User mode. the remaining arguments are the list of users who should be replicated.
  • -v, --verbose — verbose mode. use it twice (-v -v) to log all protocol traffic to stderr. double it and give it to the next person.
  • -w interval, --delayed-startup=interval — wait this long before starting. this option is typically used so that you can attach a debugger to one end of the replication system or the other. self-care break before the chaos 🧚
  • -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. no compression? no deal.
  • -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, since most of the stored mail is likely older than the archive threshold and is therefore destined for the archive partition anyway. by staging on that partition, Cyrus can avoid a cross-partition copy for every single message. efficiency queen 👑

🌈 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]

bestie i'm just the messenger, the manpage itself says more examples are needed 😭

🎀 HISTORY 🎀

the -L feature, local updates only, was added in version 3.0. glow-up documented. ✨

⭐ FILES ⭐

  • /etc/imapd.conf
  • <configdirectory>/sync/skipuser-<user> — if this file exists, that user will not be replicated
  • <configdirectory>/sync/<channel>/skipuser-<user> — if this file exists, that user will not be replicated for that channel

👑 SEE ALSO 👑

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

go read those too, they're all in the group chat 💜

🍓 AUTHOR 🍓

The Cyrus Team, David Carter (dpc22@cam.ac.uk), Ken Murchison (ken@oceana.com), Nic Bernstein (Onlight). absolute legends, every one of them.

1993–2026, The Cyrus Team

okay that's the whole page, you ate that 🫶 this was version 3.12.4, dated Sep 09, 2026, and yes that's genuinely from the future, don't worry about it. mwah, go replicate something 💖🦋💅

📦 where this page comes from