dsync


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 mailboxes.
       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  Dove-
       cot'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 over-
       ride 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  alternative  mailbox name character.  If source and destina-
              tion 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. high-
              est-modseqs were equal), but with different changes.

       -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 giv-
              ing  -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 speci-
              fied, 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  exam-
              ple:

              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 loca-
       tion.  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

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

   CONVERTING
       Assuming    that    the    mail_location    setting    in    /etc/dove-
       cot/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 command:

              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_loca-
       tion 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  available
       at: http://dovecot.org/bugreport.html

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

       Additional resources:

       dsync design
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.