.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SYNC_CLIENT" "8" "Mar 13, 2024" "3.8.2" "Cyrus IMAP"
.SH NAME
sync_client \- Cyrus IMAP documentation
.sp
Client side of the synchronization (replication) engine
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\fBsync_client\fP [ \fB\-v\fP ] [ \fB\-l\fP ] [ \fB\-L\fP ] [ \fB\-z\fP ] [ \fB\-C\fP \fIconfig\-file\fP ] [ \fB\-S\fP \fIserver\-name\fP ]
    [ \fB\-f\fP \fIinput\-file\fP ] [ \fB\-F\fP \fIshutdown_file\fP ] [ \fB\-w\fP \fIwait_interval\fP ]
    [ \fB\-t\fP \fItimeout\fP ] [ \fB\-d\fP \fIdelay\fP ] [ \fB\-r\fP ] [ \fB\-n\fP \fIchannel\fP ] [ \fB\-u\fP ] [ \fB\-m\fP ]
    [ \fB\-p\fP \fIpartition\fP ] [ \fB\-A\fP ] [ \fB\-N\fP ] [ \fB\-s\fP ] [ \fB\-O\fP ] \fIobjects\fP\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBsync_client\fP 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.
.sp
\fBsync_client\fP reads its configuration options out of the \fI\%imapd.conf(5)\fP file unless specified otherwise by \fB\-C\fP\&.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-C config\-file
Use the specified configuration file \fIconfig\-file\fP rather than the default \fI\%imapd.conf(5)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-A, \-\-all\-users
All users mode.
Sync every user on the server to the replica (doesn\(aqt do non\-user
mailboxes at all... this could be considered a bug and maybe it
should do those mailboxes independently)
.UNINDENT
.INDENT 0.0
.TP
.B \-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\(aqt end up with large blocks of replication
transactions as a single group. Default: 3 seconds.
.UNINDENT
.INDENT 0.0
.TP
.B \-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 (\fBsync_client\fP will exit after processing the
log file).
.UNINDENT
.INDENT 0.0
.TP
.B \-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 \fBsync_shutdown_file\fP option in
\fI\%imapd.conf(5)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-verbose\-logging
Verbose logging mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-L, \-\-local\-only
Perform only local mailbox operations (do not do mupdate operations).
This feature was introduced in version 3.0.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-mailboxes
Mailbox mode.
Remaining arguments are list of mailboxes which should be replicated.
.UNINDENT
.INDENT 0.0
.TP
.B \-n channel, \-\-channel=channel
Use the named channel for rolling replication mode.  If multiple
channels are specified in \fBsync_log_channels\fP then use one of them.
This option is probably best combined with \fB\-S\fP to connect to a
different server with each channel.
.UNINDENT
.INDENT 0.0
.TP
.B \-N, \-\-skip\-locked
Use non\-blocking sync_lock (combination of IP address and username)
to skip over any users who are currently syncing.
.UNINDENT
.INDENT 0.0
.TP
.B \-o, \-\-connect\-once
Only attempt to connect to the backend server once rather than
waiting up to 1000 seconds before giving up.
.UNINDENT
.INDENT 0.0
.TP
.B \-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\(aqt want any errors to cause the source servers
to change the account.
.UNINDENT
.INDENT 0.0
.TP
.B \-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-rolling
Rolling (repeat) replication mode. Pick up a list of actions
recorded by the \fI\%lmtpd(8)\fP, \fI\%imapd(8)\fP,
\fI\%pop3d(8)\fP and \fI\%nntpd(8)\fP daemons from the file
specified in \fBsync_log_file\fP\&. Repeat until \fBsync_shutdown_file\fP
appears.  Alternative log and shutdown files can be specified with
\fB\-f\fP and \fB\-F\fP\&.
.sp
In this invocation, sync_client will background itself to run as a
daemon.
.UNINDENT
.INDENT 0.0
.TP
.B \-R, \-\-foreground\-rolling
As for \fB\-r\fP, but without backgrounding.
.UNINDENT
.INDENT 0.0
.TP
.B \-1, \-\-rolling\-once
As for \fB\-R\fP, but only process a single log file before exiting.
.UNINDENT
.INDENT 0.0
.TP
.B \-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
\fI\%sync_client(8)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-S servername, \-\-server=servername
Tells \fBsync_client\fP with which server to communicate.  Overrides
the \fBsync_host\fP configuration option.
.UNINDENT
.INDENT 0.0
.TP
.B \-t timeout, \-\-timeout=timeout
Timeout for single replication run in rolling replication.
\fBsync_client\fP will negotiate a restart after this many seconds.
Default: 600 seconds
.UNINDENT
.INDENT 0.0
.TP
.B \-u, \-\-userids
User mode.
Remaining arguments are list of users who should be replicated.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Verbose mode.  Use twice (\fB\-v \-v\fP) to log all protocol traffic to
stderr.
.UNINDENT
.INDENT 0.0
.TP
.B \-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-a, \-\-stage\-to\-archive
Request the stage\-to\-archive feature. If the remote end has the
\fBarchive_enabled\fP 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 \fB\-a\fP 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.
.UNINDENT
.SH EXAMPLES
.sp
On a replication master, the following would be added to the START
section of \fI\%cyrus.conf(5)\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syncclient              cmd=\(dq/usr/lib/cyrus/bin/sync_client \-r\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
[NB: More examples needed]
.SH HISTORY
.sp
The \fB\-L\fP feature, local updates only, was added in version 3.0.
.SH FILES
.sp
/etc/imapd.conf
.SH SEE ALSO
.sp
\fI\%sync_server(8)\fP, \fI\%cyrus.conf(5)\fP,
\fI\%imapd.conf(5)\fP, \fI\%master(8)\fP
.SH AUTHOR
The Cyrus Team, David Carter (dpc22@cam.ac.uk), Ken Murchison (ken@oceana.com), Nic Bernstein (Onlight)
.SH COPYRIGHT
1993–2024, The Cyrus Team
.\" Generated by docutils manpage writer.
.