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