DSYNC(1)							      Dovecot								  DSYNC(1)

NAME

       dsync - Dovecot's mailbox synchronization utility

SYNOPSIS

       dsync [options] mirror location2
       dsync [options] backup location2

DESCRIPTION

       dsync  is  Dovecot's mailbox synchronization utility.  It can be used for several different use cases: Two-way synchronization of mailboxes
       in different servers (via ssh(1)), creating backups of mails to a remote server, and convert mailboxes from/to different mailbox formats.

       The syncing is done as perfectly as possible: an IMAP or a POP3 client shouldn't be able to notice any differences between  the	two  mail-
       boxes.  Two-way syncing means that it's safe to do any kind of modifications in both sides, and dsync will merge the changes without losing
       any changes done on either side. This is possible because dsync can access Dovecot's index logs that keep track of changes. It's of  course
       possible to have conflicts during merging, these are resolved in a safe way. See the dsync design document for more information.

       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	dsync  program	it
       works the same way: it uses its own local configuration.

       dsync can be run completely standalone. It doesn't require any Dovecot server processes to be running, except when using -u parameter to do
       a userdb lookup from auth process.

       dsync can currently sync only one user at a time. If you want to dsync all users, you'll need to get a list of all users and execute  dsync
       separately for each one.

       Any errors are written to stderr.

OPTIONS

       dsync recognizes the following command line options:

       -c config-file
	      read  configuration from the given config-file.  By default /etc/dovecot/dovecot.conf will be used.  -C alt_char Specifies an alter-
	      native mailbox name character.  If source and destination mailbox formats are different, it's possible that on one side there exists
	      a mailbox name that isn't valid for the other side.  These invalid mailbox names are fixed by replacing such invalid characters with
	      the given alt_char.  The default is '_'.

       -D     Activates debug messages and makes dsync more verbose.

       -f     Makes dsync run in "full sync" mode rather than "fast sync" mode.  In fast sync mode 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.

       -k     Preserve the existing environment variables, useful when using dsync with the SSH agent.

       -m mailbox
	      Specifies  the  mailbox  that  should  be  synchronized  or from which mails should be converted.  The default is to synchronize all
	      respectively convert from all mailboxes.

       -o setting=value
	      Overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value.  In order  to  override
	      multiple settings, the -o option may be specified multiple times.

       -R     Reverse backup direction, so mails in location2 are backed up to default mail location.

       -u user
	      Specifies  that  the  userdb lookup for the given user should be done and used to set up the environment (uid, gid, home, etc.).	By
	      default the system user's current environment will be used.

       -v     Makes dsync more verbose.

ARGUMENTS

       location2
	      The first mail location is based on configuration (mail_location or userdb settings).  It's also possible to override it	by  giving
	      -o mail_location=mail_location setting.  This parameter defines the other mail location that is used.

	      If the location is on local filesystem, you can use a regular mail_location, such as maildir:/backup/user/Maildir

	      If the location is on a remote server, dsync can ssh to it by giving host or user@host as the parameter.	If user is specified, it's
	      given as -u parameter to dsync, not to ssh.  The ssh username is always the default.

	      The final way to specify a location is to give a full command line or a path to a script that executes the dsync.  For example:

	      ssh mailuser@host dsync -u user

COMMANDS

       dsync provides the following commands:

   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.

   backup
       Backup  mails  from  default  mail location to location2 (or vice versa, if -R parameter is given).  No changes are ever done to the source
       location.  Any changes done in destination are discarded.

EXIT STATUS

       dsync will exit with one of the following values:

       0   Synchronization was done perfectly.

       2   Synchronization was done without errors, but some changes couldn't be done, so the mailboxes  aren't  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.

       1, >2
	   Synchronization failed.

EXAMPLE

   MIRRORING
       Mirror mailboxes to a remote server.  Any errors are written to stderr.

	      dsync -u username mirror username@example.com

       If you need more complex parameters to ssh, you can use e.g.:

	      dsync -u username mirror ssh -i id_dsa.dovecot mailuser@example.com dsync -u username

   CONVERTING
       Assuming that the mail_location setting in /etc/dovecot/conf.d/10-mail.conf is set to: 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 com-
       mand:

	      dsync mirror maildir:~/Maildir

       If you want to do this without any downtime, you can do the conversion one user at a time.  Initially:

	   o   Configuration uses mail_location = maildir:~/Maildir

	   o   Set up the possibility of doing per-user mail location using userdb extra fields.

       Then for each user:

	   1.  Run dsync mirror once to do the initial conversion.

	   2.  Run 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.

	   3.  Update mail extra field in userdb to mdbox:~/mdbox.  If you're using auth cache, you need to flush it.

	   4.  Wait for a few seconds and then kill the user's all existing imap and pop3 sessions (that are still using maildir).

	   5.  Run  dsync  mirror  once  more  to  apply final changes that were possibly done.  After this there should be no changes to Maildir,
	       because the user's mail location has been changed and all existing processes using it have been killed.

       Once all users have been converted, you can set the default mail_location to mdbox and remove the per-user mail locations from userdb.

REPORTING BUGS

       Report bugs, including doveconf -n output, to the Dovecot Mailing List <dovecot@dovecot.org>.  Information about reporting bugs	is  avail-
       able at: http://dovecot.org/bugreport.html

SEE ALSO

       doveadm(1), doveadm-kick(1), doveconf(1), dovecot(1)

       Additional resources:

       dsync design
	      http://wiki2.dovecot.org/Design/Dsync

Dovecot v2.1							    2011-01-16								  DSYNC(1)