Ubuntu Manpage: dsync - Dovecot's mailbox synchronization utility

name
synopsis
description
options
arguments
commands
exit status
example
reporting bugs
see also

Provided by: dovecot-core_2.2.9-1ubuntu2.6_amd64

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