Provided by: dovecot-core_2.2.9-1ubuntu2_amd64 bug

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

       -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 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:

           ·   Configuration uses mail_location = maildir:~/Maildir

           ·   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   available   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