.TH "DOVEADM-BACKUP" "1" "March 2025" "78ffb79" "Dovecot"
.SH "NAME"
\fBdoveadm-backup\fR - Dovecot's one-way mailbox synchronization feature
.SH "SYNOPSIS"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] \fBsync\fR \[lB]\fB-u\fR \fIuser\fR | \fB-A\fR | \fB-F\fR \fIfile\fR | \fB--no-userdb-lookup\fR\[rB] \[lB]\fB-S\fR \fIsocket_path\fR\[rB] \[lB]\fB-1fPR\fR\[rB] \[lB]\fB-l\fR \fIsecs\fR\[rB] \[lB]\fB-r\fR \fIrawlog path\fR\[rB] \[lB]\fB-m\fR \fImailbox\fR\[rB] \[lB]\fB-g\fR \fImailbox guid\fR\[rB] \[lB]\fB-n\fR \fInamespace\fR | \fB-N\fR\[rB] \[lB]\fB-x\fR \fIexclude\fR\[rB] \[lB]\fB-a\fR \fIall mailbox\fR\[rB] \[lB]\fB-s\fR \fIstate\fR\[rB] \[lB]\fB-T\fR \fIsecs\fR\[rB] \[lB]\fB-t\fR \fIstart date\fR\[rB] \[lB]\fB-e\fR \fIend date\fR\[rB] \[lB]\fB-O\fR \fIsync flag\fR\[rB] \[lB]\fB-I\fR \fImax size\fR\[rB] \[lB]\fB-p\fR \fIsetting=value\fR\[rB] \fIdestination\fR
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] \fBbackup\fR \[lB]\fB-u\fR \fIuser\fR | \fB-A\fR | \fB-F\fR \fIfile\fR | \fB--no-userdb-lookup\fR\[rB] \[lB]\fB-S\fR \fIsocket_path\fR\[rB] \[lB]\fB-fPR\fR\[rB] \[lB]\fB-l\fR \fIsecs\fR\[rB] \[lB]\fB-r\fR \fIrawlog path\fR\[rB] \[lB]\fB-m\fR \fImailbox\fR\[rB] \[lB]\fB-g\fR \fImailbox guid\fR\[rB] \[lB]\fB-n\fR \fInamespace\fR | \fB-N\fR\[rB] \[lB]\fB-x\fR \fIexclude\fR\[rB] \[lB]\fB-a\fR \fIall mailbox\fR\[rB] \[lB]\fB-s\fR \fIstate\fR\[rB] \[lB]\fB-T\fR \fIsecs\fR\[rB] \[lB]\fB-t\fR \fIstart date\fR\[rB] \[lB]\fB-e\fR \fIend date\fR\[rB] \[lB]\fB-O\fR \fIsync flag\fR\[rB] \[lB]\fB-I\fR \fImax size\fR\[rB] \[lB]\fB-p\fR \fIsetting=value\fR\[rB] \fIdestination\fR
.SH "DESCRIPTION"
.P
dsync (short for doveadm sync) is Dovecot's mailbox synchronization feature. It can be used for several different use cases: Two-way synchronization of mailboxes, creating backups of mails, and convert mailboxes 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.
.P
You can run dsync in one of three modes:
.RS 0
.IP \(bu 4
\fBdoveadm backup\fR performs one-way synchronization. If there are any changes in the destination they will be reverted, so the destination will look exactly like the source.
.IP \(bu 4
\fBdoveadm sync\fR performs two-way synchronization. It merges all changes without losing anything. Both the mailboxes will end up looking identical after the synchronization is finished.
.IP \(bu 4
\fBdoveadm sync -1\fR 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 currently work perfectly, so its use should be limited. Its main purpose is that during mailbox migration you can run \fBdoveadm backup\fR multiple times, then switch mails to be delivered to the new mailbox and run \fBdoveadm sync -1\fR once more to transfer any last new mails from the old mailbox.
.RS 4
.IP \(bu 4
The one-way algorithm is the same as two-way dsync algorithm except the source account is not modified. It fetches the message's GUID (Global UID), which is used to identify any conflicting UIDs in messages. As long as the source and destination side has matching UID<->GUID mapping, those emails are assumed to be synced correctly. Only after the first mismatch will changes begin.
.P
Example: Source mailbox has messages UID 1..5; source mailbox is sync'd using \fBdoveadm backup\fR 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 headers. UID 6 is not seen in destination so it's copied.
.P
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 mailbox 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 \fBdoveadm backup\fR or \fBdoveadm sync\fR command was used to synchronize the mailboxes.
.RE 0

.RE 0

.P
There are also three different synchronization algorithms:
.RS 0
.IP \(bu 4
Full synchronization (-f parameter) scans through all the messages in all the mailboxes. This guarantees that everything will be synchronized, but it's unnecessarily slow for incremental synchronization.
.IP \(bu 4
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). Usually 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 different.
.IP \(bu 4
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.
.RE 0

.P
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 \fIdsync design\fR document for more information.
.P
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 override specific settings. When executing a remote dsync program it works the same way: it uses its own local configuration.
.P
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 \fIuserdb\fR lookup from auth process.
.P
dsync can sync either one or multiple users using the -u or -A parameters.
.SH "GLOBAL OPTIONS"
.P
Global doveadm(1) 
.P
\fB-D\fR
.RS 0
.RS 4
.P
Enables \fIverbosity\fR and debug messages.
.RE 0

.RE 0

.P
\fB-O\fR
.RS 0
.RS 4
.P
Do not read any config file, just use defaults. The \fBdovecot_storage_version\fR setting defaults to the latest version, but can be overridden with 
.RE 0

.RE 0

.P
\fB-k\fR
.RS 0
.RS 4
.P
Preserve entire environment for doveadm, not just \fBimport_environment\fR setting.
.RE 0

.RE 0

.P
\fB-v\fR
.RS 0
.RS 4
.P
Enables verbosity, including progress counter.
.RE 0

.RE 0

.P
\fB-i\fR \fIinstance-name\fR
.RS 0
.RS 4
.P
If using multiple Dovecot instances, choose the config file based on this instance name.
.P
See \fBinstance_name\fR setting for more information.
.RE 0

.RE 0

.P
\fB-c\fR \fIconfig-file\fR
.RS 0
.RS 4
.P
Read configuration from the given \fIconfig-file\fR. By default it first reads config socket, and then falls back to \fI/etc/dovecot/dovecot.conf\fR. You can also point this to config socket of some instance running compatible version.
.RE 0

.RE 0

.P
\fB-o\fR \fIsetting\fR\fB=\fR\fIvalue\fR
.RS 0
.RS 4
.P
Overrides the configuration \fIsetting\fR from \fI/etc/dovecot/dovecot.conf\fR and from the userdb with the given \fIvalue\fR. In order to override multiple settings, the \fB-o\fR option may be specified multiple times.
.RE 0

.RE 0

.SH "OPTIONS"
.P
\fB-A\fR
.RS 0
.RS 4
.P
If the \fB-A\fR option is present, the \fIcommand\fR will be performed for all users. Using this option in combination with system users from \fBuserdb { driver = passwd }\fR is not recommended, because it contains also users with a lower UID than the one configured with the \fBfirst_valid_uid\fR setting.
.P
When the SQL userdb module is used, make sure that the \fBuserdb_sql_iterate_query\fR setting setting matches your database layout.
.P
When using the LDAP userdb module, make sure that the \fBuserdb_fields\fR setting and \fBuserdb_ldap_iterate_fields\fR setting settings match your LDAP schema. Otherwise doveadm(1) will be unable to iterate over all users.
.RE 0

.RE 0

.P
\fB-F\fR \fIfile\fR
.RS 0
.RS 4
.P
Execute the \fIcommand\fR for all the users in the \fIfile\fR. This is similar to the \fB-A\fR option, but instead of getting the list of users from the userdb, they are read from the given \fIfile\fR. The \fIfile\fR contains one username per line.
.RE 0

.RE 0

.P
\fB-1\fR
.RS 0
.RS 4
.P
Do one-way synchronization instead of two-way synchronization.
.RE 0

.RE 0

.P
\fB-f\fR
.RS 0
.RS 4
.P
Do full synchronization.
.RE 0

.RE 0

.P
\fB-N\fR
.RS 0
.RS 4
.P
Synchronize all the available namespaces. By default only the inbox=yes namespace is synchronized.
.RE 0

.RE 0

.P
\fB--no-userdb-lookup\fR
.RS 0
.RS 4
.P
Do not perform userdb lookup. Use the \fBUSER\fR environment variable to specify the username.
.RE 0

.RE 0

.P
\fB-P\fR
.RS 0
.RS 4
.P
Run a doveadm-purge(1) for the destination (remote) storage after synchronization.
.RE 0

.RE 0

.P
\fB-R\fR
.RS 0
.RS 4
.P
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.
.RE 0

.RE 0

.P
\fB-S\fR \fIsocket_path\fR
.RS 0
.RS 4
.P
The option's argument is either an absolute path to a local UNIX domain socket, or a hostname and port (\fIhostname\fR:\fIport\fR), in order to connect a remote host via a TCP socket.
.P
This allows an administrator to execute doveadm(1) mail commands through the given socket.
.RE 0

.RE 0

.P
\fB-T\fR \fIsecs\fR
.RS 0
.RS 4
.P
Specify the time in seconds, how long doveadm(1) should wait for stalled I/O operations. The default timeout is 600 seconds.
.RE 0

.RE 0

.P
\fB-p\fR \fIsetting\fR\fB=\fR\fIvalue\fR
.RS 0
.RS 4
.P
Overrides the configuration \fIsetting\fR for source storage.
.RE 0

.RE 0

.P
\fB-p\fR \fIsetting\fR\fB=\fR\fIvalue\fR
.RS 0
.RS 4
.P
Overrides the configuration \fIsetting\fR for source storage.
.RE 0

.RE 0

.P
\fB-g\fR \fImailbox_guid\fR
.RS 0
.RS 4
.P
Same as -m, but find the mailbox to be synchronized by its GUID instead of by name.
.RE 0

.RE 0

.P
\fB-l\fR \fIsecs\fR
.RS 0
.RS 4
.P
Lock the dsync for this user. Wait for maximum \fIsecs\fR 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.
.RE 0

.RE 0

.P
\fB-m\fR \fImailbox\fR
.RS 0
.RS 4
.P
Synchronize only this mailbox name.
.RE 0

.RE 0

.P
\fB-n\fR \fInamespace\fR
.RS 0
.RS 4
.P
Synchronize only the specified namespace. This parameter can be used multiple times.
.RE 0

.RE 0

.P
\fB-a\fR \fIall mailbox\fR
.RS 0
.RS 4
.P
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.
.RE 0

.RE 0

.P
\fB-t\fR \fIstart date\fR
.RS 0
.RS 4
.P
Skip any mails whose received-timestamp is older than the specified time.
.RE 0

.RE 0

.P
\fB-e\fR \fIend date\fR
.RS 0
.RS 4
.P
Skip any mails whose received-timestamp is newer than the specified time.
.RE 0

.RE 0

.P
\fB-O\fR \fIsync flag\fR
.RS 0
.RS 4
.P
Sync only mails that have the specified flag. If the flag name begins with "\fB-\fR", sync all mails except the ones with the specified flag.
.RE 0

.RE 0

.P
\fB-I\fR \fImax size\fR
.RS 0
.RS 4
.P
Skip any mails larger than the specified size.
.RE 0

.RE 0

.P
\fB-r\fR \fIrawlog_path\fR
.RS 0
.RS 4
.P
Running dsync remotely, write the remote input/output traffic to the specified log file.
.RE 0

.RE 0

.P
\fB-s\fR \fIprevious_state\fR
.RS 0
.RS 4
.P
Use stateful synchronization. If the previous state is unknown, use an empty string. The new state is always printed to standard output.
.RE 0

.RE 0

.P
\fB-u\fR \fIuser/mask\fR
.RS 0
.RS 4
.P
Run the \fIcommand\fR only for the given \fIuser\fR. It's also possible to use '\fB*\fR' and '\fB?\fR' wildcards (e.g. -u *@example.org).
.RE 0

.RE 0

.P
\fB-x\fR \fImailbox_mask\fR
.RS 0
.RS 4
.P
Exclude the specified mailbox name/mask. The mask may contain "\fB?\fR" and "*****" wildcards. The mask can also be a special-use name (e.g. \[rs]Trash). This parameter can be used multiple times.
.RE 0

.RE 0

.SH "ARGUMENTS"
.P
\fIdestination\fR
.RS 0
.RS 4
.P
This argument specifies the synchronized destination.
.P
It can be one of:
.RS 4
.P
\fImail_driver:mail_path\fR : Uses the storage specified by \fImail_driver\fR and \fImail_path\fR. Use the \fB-p\fR parameter to specify additional settings.
.RE 0

.RS 4
.P
\fBremote:\fR \fIlogin@host\fR : Uses \fIdsync_remote_cmd\fR setting to connect to the remote host (usually via ssh)
.RE 0

.RS 4
.P
\fIremoteprefix:login@host\fR : This is the same as remote, except "user@domain\[rs]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.
.RE 0

.RS 4
.P
\fBtcp:\fR \fIhost\[lB]:port\[rB]\fR : Connects to remote doveadm server via TCP. The default port is specified by \fIdoveadm_port\fR setting.
.RE 0

.RS 4
.P
\fBtcps:\fR \fIhost\[lB]:port\[rB]\fR : This is the same as tcp, but with SSL.
.RE 0

.RS 4
.P
\fBcommand \[lB]arg1 \[lB], arg2, ...\[rB]\[rB]\fR : Runs a local command that connects its standard input & output to a dsync server.
.RE 0

.RE 0

.RE 0

.SH "EXIT STATUS"
.P
\fBdsync\fR will exit with one of the following values:
.P
\fB0\fR
.RS 0
.RS 4
.P
Synchronization was done perfectly.
.RE 0

.RE 0

.P
\fB2\fR
.RS 0
.RS 4
.P
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.
.RE 0

.RE 0

.P
\fB1, >2\fR
.RS 0
.RS 4
.P
Synchronization failed.
.RE 0

.RE 0

.P
See also doveadm(1) for other possible error codes.
.SH "EXAMPLE"
.SS "SYNCHRONIZATION"
.P
Synchronize mailboxes with a remote server. Any errors are written to stderr:
.P
.RS 2
.nf
doveadm sync -u username@example.com remote:server-replica.example.com
.fi
.RE
.P
If you need more complex parameters to ssh, you can use e.g.:
.P
.RS 2
.nf
doveadm sync -u username@example.com ssh -i id_dsa.dovecot \[rs]
  mailuser@example.com doveadm dsync-server -u username@example.com
.fi
.RE
.SS "CONVERTING"
.P
Example to convert mails from Maildir format to the format specified in the configuration file:
.P
.RS 2
.nf
doveadm backup -u user maildir:~/Maildir
.fi
.RE
.P
If you want to do this without any downtime, you can do the conversion one user at a time. Initially:
.RS 0
.IP \(bu 4
Configuration uses \fBmail_driver = maildir\fR and \fBmail_path = ~/Maildir\fR
.IP \(bu 4
Set up the possibility of doing per-user mail location using \fIuserdb\fR extra fields.
.RE 0

.P
Then for each user:
.RS 0
.IP 1. 4
Run \fIdoveadm sync\fR once to do the initial conversion.
.IP 2. 4
Run \fIdoveadm sync\fR 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.
.IP 3. 4
Update userdb to return the wanted new mail format configuration. For example: \fBmail_driver = mdbox\fR and \fBmail_path = ~/mdbox\fR. If you're using auth cache, you need to flush it, e.g. \fBdoveadm auth cache flush\fR.
.IP 4. 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).
.IP 5. 4
Run \fIdoveadm sync\fR 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.
.RE 0

.P
Once all users have been converted, you can update the global \fImail_driver\fR and \fImail_path\fR settings and remove the per-user mail locations from \fIuserdb\fR.
.SH "REPORTING BUGS"
.P
Report bugs, including \fIdoveconf -n\fR output, to the Dovecot Mailing List \fI\(ladovecot@dovecot.org\(ra\fR. Information about reporting bugs is available at: https://dovecot.org/bugreport.html
.SH "SEE ALSO"
.P
doveadm(1), doveadm-purge(1)