Sync or Back Up Dovecot Mailboxes with doveadm sync

Pick the wrong one of doveadm sync and doveadm backup and you can wipe mail from the destination. You will end up with a checked command for copying one Dovecot mailbox set to another location, plus a safe choice between two-way synchronisation and a one-way backup. The examples match dovecot-core version 1:2.3.21+dfsg1-2ubuntu6.5 installed on this machine. Allow about fifteen minutes for a dry run and a further ten minutes if you are planning a migration.

You need a working Dovecot configuration, access to the mailbox storage, and a destination that the Dovecot process can read and write. Use sudo only where the mailbox permissions require it.

1. Choose the operation before the command

The names are easy to confuse.

• doveadm sync is two-way. Changes from both sides are merged and the mailboxes should end up equivalent.
• doveadm backup is one-way. The destination is made to match the source, so changes present only at the destination can be removed.
• dsync is the old name. It refers to the same feature and is installed here as a compatibility command.

Use sync when both mailboxes are active and changes on either side must survive. Use backup when the destination is a disposable replica or backup. Do not use backup against a mailbox that contains unique mail until you have confirmed that the source is complete.

2. Check the local installation and account

Confirm the command path and the package version without changing mail:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

Run the operation as the account that owns the storage, or use the service account and its normal configuration. How the user is chosen matters:

• -u: Dovecot may use the auth process for a userdb lookup.
• No -u, -A or -F: the command uses the currently logged-in user's environment.
• -F FILE: reads one username per line, for several users.
• -A: obtains users from the userdb and needs a correctly configured iteration query.

$ sudo doveconf -n

Pay particular attention to mail_location, userdb settings, and any replica destination. The sync operation can run without Dovecot server processes, except that a -u userdb lookup may contact the auth process.

3. Run a two-way remote synchronisation

A remote destination normally uses Dovecot's dsync_remote_cmd setting, commonly an SSH command. Replace both placeholders with real values and keep the username explicit:

$ sudo doveadm sync -u [email protected] remote:replica.example.net

The destination syntax is not a general URL. The remote: form uses the configured remote command. Other supported forms include tcp:HOST[:PORT], tcps:HOST[:PORT], a local mailbox location such as maildir:~/Maildir, and a local command connected to a dsync server.

For a more complex SSH invocation, pass the command that starts the remote protocol:

$ sudo doveadm sync -u [email protected] \
  ssh -i /path/to/replica-key \
  [email protected] doveadm dsync-server -u [email protected]

The command writes errors to standard error. Exit codes tell you how it went:

• Status 0: the synchronisation completed perfectly.
• Status 2: it completed without a hard error, but some changes could not be applied, often because a mailbox changed during the run.
• Status 1 or above 2: failure. Read the error before retrying, because a repeated failure can point to a permission, connection, configuration or storage problem.

Run it again and require status 0 before calling a final migration complete:

$ status=$?
$ printf 'doveadm status: %s\n' "$status"
doveadm status: 0

4. Create a one-way backup or convert storage

For a destination that should mirror the source, use backup. This example copies the configured mailbox format into a Maildir destination:

$ sudo doveadm backup -u [email protected] maildir:/srv/mail-backups/USER/Maildir
$ status=$?
$ printf 'backup status: %s\n' "$status"

Check the destination with the storage tools appropriate to your format, and keep the original until you have inspected several folders and messages.

For a format conversion, the destination can be a local location while mail_location remains the configured source format. The local manual gives the example doveadm sync maildir:~/Maildir when the configured location is mdbox. For a live conversion, follow this order:

1. Sync once. Run an initial sync.
2. Sync again. Catch mail received during the first pass.
3. Change the location. Update the per-user mail location.
4. End old sessions. Terminate IMAP and POP3 sessions still using the old location.
5. Sync a final time.

Treat the location change and session termination as a maintenance operation, not part of a casual test.

5. Make incremental runs safer and more predictable

The default fast algorithm checks mailbox metadata and normally avoids scanning unchanged mailboxes. Use -f for a full synchronisation when you need every mailbox and message checked. It is slower, and it is not a repair for an unknown destination.

For repeated incremental runs, -s enables stateful synchronisation. Start with an empty state, capture the new state printed on standard output, and pass that exact value to the next run:

$ state=$(sudo doveadm sync -u [email protected] -s '' remote:replica.example.net)
$ printf 'new sync state: %s\n' "$state"
$ sudo doveadm sync -u [email protected] -s "$state" remote:replica.example.net

Do not edit, wrap or casually log the state string. Keep it with the mailbox job and replace it only with the state from a successful later run. If the state or either mailbox is corrupted, discard the state and do a fresh synchronisation, as the local manual recommends.

Narrowing options do not make an unsafe destination safe:

• -l SECONDS: use it when more than one job might run for the same user. It waits for the per-user dsync lock and then gives up.
• -m MAILBOX: a single mailbox.
• -n NAMESPACE: a namespace.
• Repeated -x MASK: exclude mailboxes.

6. Use migration filters only with an explicit scope

These filters intentionally produce a partial mailbox, so do not mistake a successful exit for a complete migration.

• -t and -e: limit messages by received timestamp.
• -I SIZE: skips messages larger than the specified size.
• -O FLAG: synchronises only messages carrying a flag. Prefix the flag with a hyphen to select messages without it.

-P runs a purge on the remote destination after synchronisation. Keep it for a documented retention workflow.

7. Know the version boundary

This host is on Dovecot 2.3.21. Current Dovecot documentation describes the same sync and backup concepts, but Dovecot 2.4 removed the standalone dsync command symlink. For portable procedures, write doveadm sync or doveadm backup explicitly and do not depend on dsync being present. Re-check the installed manpage when moving the procedure to a different major version.