| |
dsync(1) - phpMan
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)), creat‐
ing 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 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/dove‐
cot.conf will be used. -C alt_char Specifies an alternative mailbox name charac‐
ter. 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 mail‐
boxes.
-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 loca‐
tion.
-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 set‐
tings). 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. Typi‐
cally 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 AT 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 AT 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 ses‐
sions (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@dove‐
cot.org>. Information about reporting bugs is available at: http://dovecot.org/bugre‐
port.html
SEE ALSO
doveadm(1), doveadm-kick(1), doveconf(1), dovecot(1)
Additional resources:
dsync design
http://wiki2.dovecot.org/Design/Dsync
Dovecot v2.2 2011-01-16 DSYNC(1)
|
