DOVEADM-SYNC(1) Dovecot DOVEADM-SYNC(1)
NAME
doveadm-sync - Dovecot's two-way mailbox synchronization feature
SYNOPSIS
doveadm [GLOBAL OPTIONS] sync [-u user | -A | -F file | --no-userdb-
lookup] [-S socket_path] [-1fPR] [-l secs] [-r rawlog path] [-m mail-
box] [-g mailbox guid] [-n namespace | -N] [-x exclude] [-a all mail-
box] [-s state] [-T secs] [-t start date] [-e end date] [-O sync flag]
[-I max size] [-p setting=value] destination
doveadm [GLOBAL OPTIONS] backup [-u user | -A | -F file | --no-userdb-
lookup] [-S socket_path] [-fPR] [-l secs] [-r rawlog path] [-m mailbox]
[-g mailbox guid] [-n namespace | -N] [-x exclude] [-a all mailbox] [-s
state] [-T secs] [-t start date] [-e end date] [-O sync flag] [-I max
size] [-p setting=value] destination
DESCRIPTION
dsync (short for doveadm sync) is Dovecot's mailbox synchronization
feature. It can be used for several different use cases: Two-way syn-
chronization of mailboxes, creating backups of mails, and convert mail-
boxes from/to different mailbox formats. All of these can be used
within the same server or between different servers (via ssh(1) or tcp
connections). Remote mailboxes can be accessed also via IMAP protocol,
which allows using dsync for mailbox migration purposes.
You can run dsync in one of three modes:
o doveadm backup performs one-way synchronization. If there are any
changes in the destination they will be reverted, so the destina-
tion will look exactly like the source.
o doveadm sync performs two-way synchronization. It merges all
changes without losing anything. Both the mailboxes will end up
looking identical after the synchronization is finished.
o doveadm sync -1 performs one-way synchronization. If there are any
changes in the destination, they will be preserved and the new
changes will be merged on top of them. This merging doesn't cur-
rently work perfectly, so its use should be limited. Its main pur-
pose is that during mailbox migration you can run doveadm backup
multiple times, then switch mails to be delivered to the new mail-
box and run doveadm sync -1 once more to transfer any last new
mails from the old mailbox.
o The one-way algorithm is the same as two-way dsync algorithm
except the source account is not modified. It fetches the mes-
sage's GUID (Global UID), which is used to identify any con-
flicting UIDs in messages. As long as the source and destina-
tion side has matching UID<->GUID mapping, those emails are
assumed to be synced correctly. Only after the first mismatch
will changes begin.
Example: Source mailbox has messages UID 1..5; source mailbox is
sync'd using doveadm backup to the destination. Subsequently, UID 6
is delivered to the source mailbox and UID 1 is expunged from the
destination mailbox. In this example, UID 1 is kept removed (in
destination) because UID 1..5 have identical Date+Message-ID head-
ers. UID 6 is not seen in destination so it's copied.
If both source and destination have UID 6, but the messages are
different, the headers don't match and both the messages are kept
in the destination but they're given new UIDs 7 and 8 just to be
sure any client didn't get confused about what UID 6 actually was.
Thus, one-way sync begins to quickly diverge from the source mail-
box once changes start to occur on either side; one-way sync should
therefore normally only be used within a short period of time after
a doveadm backup or doveadm sync command was used to synchronize
the mailboxes.
There are also three different synchronization algorithms:
o Full synchronization (-f parameter) scans through all the messages
in all the mailboxes. This guarantees that everything will be syn-
chronized, but it's unnecessarily slow for incremental synchroniza-
tion.
o Fast synchronization (default) first attempts to find mailboxes
that have changed, and synchronize only those. This is done by
checking the mailboxes' metadata (NEXTUID and HIGHESTMODSEQ). Usu-
ally this works fine, especially with one-way synchronization, but
if both sides do exactly the same number of changes, the metadata
may end up containing the same values even if the changes were dif-
ferent.
o Stateful synchronization (-s parameter) is the most efficient way
to synchronize mailboxes. It relies on having the earlier dsync
run's state saved somewhere and being passed to the next dsync run.
Based on this state dsync can send only the changes that happened
after the previous dsync run. As long as the state or the mailboxes
aren't corrupted this algorithm should work perfectly.
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(1)). 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 sync either one or multiple users using the -u or -A parame-
ters.
GLOBAL OPTIONS
Global doveadm(1)
-D
Enables verbosity and debug messages.
-O
Do not read any config file, just use defaults. The dovecot_stor-
age_version setting defaults to the latest version, but can be
overridden with
-k
Preserve entire environment for doveadm, not just import_environ-
ment setting.
-v
Enables verbosity, including progress counter.
-i instance-name
If using multiple Dovecot instances, choose the config file based
on this instance name.
See instance_name setting for more information.
-c config-file
Read configuration from the given config-file. By default it first
reads config socket, and then falls back to /etc/dovecot/dove-
cot.conf. You can also point this to config socket of some instance
running compatible version.
-o setting=value
Overrides the configuration setting from /etc/dovecot/dovecot.conf
and from the userdb with the given value. In order to override mul-
tiple settings, the -o option may be specified multiple times.
OPTIONS
-A
If the -A option is present, the command will be performed for all
users. Using this option in combination with system users from
userdb { driver = passwd } is not recommended, because it contains
also users with a lower UID than the one configured with the
first_valid_uid setting.
When the SQL userdb module is used, make sure that the
userdb_sql_iterate_query setting setting matches your database lay-
out.
When using the LDAP userdb module, make sure that the userdb_fields
setting and userdb_ldap_iterate_fields setting settings match your
LDAP schema. Otherwise doveadm(1) will be unable to iterate over
all users.
-F file
Execute the command for all the users in the file. This is similar
to the -A option, but instead of getting the list of users from the
userdb, they are read from the given file. The file contains one
username per line.
-1
Do one-way synchronization instead of two-way synchronization.
-f
Do full synchronization.
-N
Synchronize all the available namespaces. By default only the
inbox=yes namespace is synchronized.
--no-userdb-lookup
Do not perform userdb lookup. Use the USER environment variable to
specify the username.
-P
Run a doveadm-purge(1) for the destination (remote) storage after
synchronization.
-R
Do a reverse sync. Normally, messages would be pushed from the
local system to the destination (remote). This option reverses the
flow, and will instead pull messages from the remote to the local
storage.
-S socket_path
The option's argument is either an absolute path to a local UNIX
domain socket, or a hostname and port (hostname:port), in order to
connect a remote host via a TCP socket.
This allows an administrator to execute doveadm(1) mail commands
through the given socket.
-T secs
Specify the time in seconds, how long doveadm(1) should wait for
stalled I/O operations. The default timeout is 600 seconds.
-p setting=value
Overrides the configuration setting for source storage.
-p setting=value
Overrides the configuration setting for source storage.
-g mailbox_guid
Same as -m, but find the mailbox to be synchronized by its GUID
instead of by name.
-l secs
Lock the dsync for this user. Wait for maximum secs before giving
up. This parameter should be used to avoid broken synchronization
if it's possible that dsync is being run concurrently for the same
user.
-m mailbox
Synchronize only this mailbox name.
-n namespace
Synchronize only the specified namespace. This parameter can be
used multiple times.
-a all mailbox
Name for the "All mails" virtual mailbox. If specified, mails are
attempted to be copied from this mailbox instead of being saved
separately. This may reduce the total disk space usage as well as
disk IO.
-t start date
Skip any mails whose received-timestamp is older than the specified
time.
-e end date
Skip any mails whose received-timestamp is newer than the specified
time.
-O sync flag
Sync only mails that have the specified flag. If the flag name
begins with "-", sync all mails except the ones with the specified
flag.
-I max size
Skip any mails larger than the specified size.
-r rawlog_path
Running dsync remotely, write the remote input/output traffic to
the specified log file.
-s previous_state
Use stateful synchronization. If the previous state is unknown, use
an empty string. The new state is always printed to standard out-
put.
-u user/mask
Run the command only for the given user. It's also possible to use
'*' and '?' wildcards (e.g. -u *@example.org).
-x mailbox_mask
Exclude the specified mailbox name/mask. The mask may contain "?"
and "*****" wildcards. The mask can also be a special-use name
(e.g. \Trash). This parameter can be used multiple times.
ARGUMENTS
destination
This argument specifies the synchronized destination.
It can be one of:
mail_driver:mail_path : Uses the storage specified by
mail_driver and mail_path. Use the -p parameter to specify
additional settings.
remote: login@host : Uses dsync_remote_cmd setting to connect to
the remote host (usually via ssh)
remoteprefix:login@host : This is the same as remote, except
"user@domain\n" is sent before dsync protocol starts. This allows
implementing a trusted wrapper script that runs doveadm dsync-
server by reading the username from the first line.
tcp: host[:port] : Connects to remote doveadm server via TCP. The
default port is specified by doveadm_port setting.
tcps: host[:port] : This is the same as tcp, but with SSL.
command [arg1 [, arg2, ...]] : Runs a local command that connects
its standard input & output to a dsync server.
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.
See also doveadm(1) for other possible error codes.
EXAMPLE
SYNCHRONIZATION
Synchronize mailboxes with a remote server. Any errors are written to
stderr:
doveadm sync -u username AT example.com remote:server-replica.example.com
If you need more complex parameters to ssh, you can use e.g.:
doveadm sync -u username AT example.com ssh -i id_dsa.dovecot \
mailuser AT example.com doveadm dsync-server -u username AT example.com
CONVERTING
Example to convert mails from Maildir format to the format specified in
the configuration file:
doveadm backup -u user 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_driver = maildir and mail_path = ~/Maildir
o Set up the possibility of doing per-user mail location using userdb
extra fields.
Then for each user:
1. Run doveadm sync once to do the initial conversion.
2. Run doveadm sync 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 userdb to return the wanted new mail format configuration.
For example: mail_driver = mdbox and mail_path = ~/mdbox. If you're
using auth cache, you need to flush it, e.g. doveadm auth cache
flush.
4. Wait for a few seconds and then kill (doveadm kick) the user's all
existing imap and pop3 sessions (that are still using maildir).
5. Run doveadm sync once more to apply final changes that were possi-
bly done. After this there should be no changes to Maildir, because
the user's mail location has been changed and all existing pro-
cesses using it have been killed.
Once all users have been converted, you can update the global
mail_driver and mail_path settings and remove the per-user mail loca-
tions from userdb.
REPORTING BUGS
Report bugs, including doveconf -n output, to the Dovecot Mailing List
<dovecot AT dovecot.org>. Information about reporting bugs is available
at: https://dovecot.org/bugreport.html
SEE ALSO
doveadm(1), doveadm-purge(1)
78ffb79 March 2025 DOVEADM-SYNC(1)
Linux-Distributionen
Huschi als Linux-Admin