.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file
.TH DSYNC 1 "2011-01-16" "Dovecot v2.2" "Dovecot"
.SH NAME
dsync \- Dovecot\(aqs mailbox synchronization utility
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.B dsync
.RI [ options ]
.BI mirror\  location2
.\"-------------------------------------
.br
.B dsync
.RI [ options ]
.BI backup\  location2
.\"------------------------------------------------------------------------
.SH DESCRIPTION
.B dsync
is Dovecot\(aqs mailbox synchronization utility.
It can be used for several different use cases:
Two\-way synchronization of mailboxes in different servers (via
.BR ssh (1)),
creating backups of mails to a remote server, and convert mailboxes from/to
different mailbox formats.
.PP
The syncing is done as perfectly as possible: an IMAP or a POP3 client
shouldn\(aqt be able to notice any differences between the two mailboxes.
Two\-way syncing means that it\(aqs safe to do any kind of modifications in
both sides, and
.B dsync
will merge the changes without losing any changes done on either side. This
is possible because
.B dsync
can access Dovecot\(aqs index logs that keep track of changes. It\(aqs of
course possible to have conflicts during merging, these are resolved in a
safe way. See the
.B dsync
design document for more information.
.PP
.B dsync
uses the same configuration files as the rest of Dovecot (via doveconf
binary). The entire configuration can be changed by giving \-c parameter to
another configuration file, or using \-o parameter to override specific
settings. When executing a remote
.B dsync
program it works the same way: it uses its own local configuration.
.PP
.B dsync
can be run completely standalone. It doesn\(aqt require any Dovecot server
processes to be running, except when using \-u parameter to do a userdb
lookup from auth process.
.PP
.B dsync
can currently sync only one user at a time. If you want to
.B dsync
all users, you\(aqll need to get a list of all users and execute
.B dsync
separately for each one.

Any errors are written to stderr.
.\"------------------------------------------------------------------------
.SH OPTIONS
.B dsync
recognizes the following command line options:
.TP
.BI \-c \ config\-file
read configuration from the given
.IR config\-file .
By default
.I @pkgsysconfdir@/dovecot.conf
will be used.
.\"---------------------------------
.BI \-C\  alt_char
Specifies an alternative mailbox name character.
If source and destination mailbox formats are different, it\(aqs possible
that on one side there exists a mailbox name that isn\(aqt valid for the
other side.
These invalid mailbox names are fixed by replacing such invalid
characters with the given
.IR alt_char .
The default is
.RB \(aq _ \(aq.
.\"---------------------------------
.TP
.B \-D
Activates debug messages and makes
.B dsync
more verbose.
.\"---------------------------------
.TP
.B \-f
Makes
.B dsync
run in \(dqfull sync\(dq mode rather than \(dqfast sync\(dq mode.
In fast sync mode
.B dsync
might skip syncing a mailbox, if both locations had modified it equally
many times (i.e. highest\-modseqs were equal), but with different changes.
.\"---------------------------------
.TP
.BI \-m\  mailbox
Specifies the
.I mailbox
that should be synchronized or from which mails should be converted.
The default is to synchronize all respectively convert from all mailboxes.
.\"---------------------------------
.TP
.BI \-o\  setting = value
Overrides the configuration
.I setting
from
.I @pkgsysconfdir@/dovecot.conf
and from the userdb with the given
.IR value .
In order to override multiple settings, the
.B \-o
option may be specified multiple times.
.\"---------------------------------
.TP
.B \-R
Reverse backup direction, so mails in
.I location2
are backed up to default mail location.
.\"---------------------------------
.TP
.BI \-u\  user
Specifies that the userdb lookup for the given
.I user
should be done and used to set up the environment (uid, gid, home, etc.).
By default the system user\(aqs current environment will be used.
.\"---------------------------------
.TP
.B \-v
Makes
.B dsync
more verbose.
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I location2
The first mail location is based on configuration
.RI ( mail_location " or " userdb " settings).
It\(aqs also possible to override it by giving
.BI \-o\ mail_location= mail_location
setting.
This parameter defines the other mail location that is used.
.sp
If the location is on local filesystem, you can use a regular
mail_location, such as maildir:/backup/user/Maildir
.sp
If the location is on a remote server,
.B dsync
can ssh to it by giving
.I host
or
.I user@host
as the parameter.
If user is specified, it\(aqs given as
.B \-u
parameter to
.BR dsync ,
not to ssh.
The ssh username is always the default.
.sp
The final way to specify a location is to give a full command line or a
path to a script that executes the
.BR dsync .
For example:
.sp
.nf
ssh mailuser@host dsync \-u user
.fi
.\"------------------------------------------------------------------------
.SH COMMANDS
.B dsync
provides the following commands:
.\"------------------------------------------------------------------------
.SS mirror
Does a two\-way synchronization between two mail locations.
Changes in both locations are synchronized to the other one, without losing
any changes made by either of them.
Any potential UID conflicts are resolved by giving them new UIDs.
.\"------------------------------------------------------------------------
.SS backup
Backup mails from default mail location to
.I location2
(or vice versa, if
.B \-R
parameter is given).
No changes are ever done to the source location.
Any changes done in destination are discarded.
.\"------------------------------------------------------------------------
.SH "EXIT STATUS"
.B dsync
will exit with one of the following values:
.TP 4
.B 0
Synchronization was done perfectly.
.TP
.B 2
Synchronization was done without errors, but some changes couldn\(aqt be done,
so the mailboxes aren\(aqt perfectly synchronized. Running dsync again
usually fixes this. Typically this occurs for message modification
sequences with newly created mailboxes. It can also occur if one of the
mailboxes change during the syncing.
.TP
.B 1, >2
Synchronization failed.
.\"------------------------------------------------------------------------
.SH EXAMPLE
.SS MIRRORING
Mirror mailboxes to a remote server.
Any errors are written to stderr.
.PP
.RS
.nf
.B dsync -u username mirror username@example.com
.fi
.RE
.PP
If you need more complex parameters to ssh, you can use e.g.:
.PP
.RS
.nf
.B dsync \-u username mirror ssh \-i id_dsa.dovecot mailuser@example.com dsync \-u username
.fi
.RE
.\"------------------------------------------------------------------------
.SS CONVERTING
Assuming that the
.I mail_location
setting in
.I @pkgsysconfdir@/conf.d/10\-mail.conf
is set to:
.BR "mail_location = mdbox:~/mdbox" ,
a logged in system user may convert her/his mails from its Maildir in
her/his home directory to the mdbox mailbox format.
The user has to execute the command:
.PP
.RS
.nf
.B dsync mirror maildir:~/Maildir
.fi
.RE
.PP
If you want to do this without any downtime, you can do the conversion one
user at a time.
Initially:
.RS 4
.IP \(bu 4
Configuration uses
.B mail_location = maildir:~/Maildir
.IP \(bu
Set up the possibility of doing per\-user mail location using
.I userdb
extra fields.
.RE
.PP
Then for each user:
.RS 4
.IP 1. 4
Run
.I dsync mirror
once to do the initial conversion.
.IP 2.
Run
.I dsync mirror
again, because the initial conversion could have taken a while and new
changes could have occurred during it.
This second time only applies changes, so it should be fast.
.IP 3.
Update mail extra field in userdb to
.BR  mdbox:~/mdbox .
If you\(aqre using auth cache, you need to flush it.
.IP 4.
Wait for a few seconds and then kill the user\(aqs all existing imap and
pop3 sessions (that are still using maildir).
.IP 5.
Run
.I dsync mirror
once more to apply final changes that were possibly done.
After this there should be no changes to Maildir, because the user\(aqs
mail location has been changed and all existing processes using it have
been killed.
.RE
.PP
Once all users have been converted, you can set the default
.I mail_location
to mdbox and remove the per\-user mail locations from
.IR userdb .
.\"------------------------------------------------------------------------
@INCLUDE:reporting-bugs@
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1),
.BR doveadm\-kick (1),
.BR doveconf (1),
.BR dovecot (1)
.\"-------------------------------------
.PP
Additional resources:
.IP "dsync design"
http://wiki2.dovecot.org/Design/Dsync