One mailbox is behind on the second server, and doveadm replicator is how you find out why and give it a shove. You will inspect replication, queue a user for immediate work, request a full pass when needed, and remove a user from the replicator. The examples match doveadm-replicator from Dovecot 2.3.21, installed here as Debian package dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5. Allow about 15 minutes if you already know the mailbox address and the replication service is running.
sudo.Read the installed command summary before using it:
$ doveadm help replicator
DOVEADM-REPLICATOR(1) Dovecot
...The manpage identifies the command as part of Dovecot v2.3. The default UNIX socket is /run/dovecot/replicator-doveadm. If base_dir has been overridden in /etc/dovecot/dovecot.conf, the socket may be elsewhere.
Check the path without changing anything:
$ ls -l /run/dovecot/replicator-doveadm
$ doveconf -n | grep '^base_dir'Checkpoint: continue only when the socket exists, or when you have found the alternative absolute path. A failed connection is not evidence that a mailbox is out of sync.
Use a quoted mask. Quoting stops the shell expanding the asterisk against local filenames:
$ sudo doveadm replicator status '*'
[email protected] priority=normal async_secs=0 success=...
...The exact fields depend on the running Dovecot configuration and status. The command asks the replicator for users matching the mask. It does not start a new replication pass. To narrow the result, use an exact username or a domain mask:
$ sudo doveadm replicator status '[email protected]'
$ sudo doveadm replicator status '*@example.net'Use -f table, -f tab, -f pager or -f flow when another program needs a predictable presentation. The default is flow output without the key= prefix. The formatter changes the display, not the replication operation.
On a host without a running replicator, the installed command reports a socket error and exits non-zero, for example:
Fatal: net_connect_unix(/run/dovecot/replicator-doveadm) failed: No such file or directory
$ printf '%s\n' "$?"
75Tip: do not read that as an empty result. Check the Dovecot service, its logs and base_dir with your normal operational process.
Queue users by passing a user mask to add:
$ sudo doveadm replicator add '[email protected]'
$ sudo doveadm replicator add '*@example.net'An exact address targets one user. A mask containing * or ? is expanded through the user database, so SQL and LDAP installations must be able to iterate their users.
iterate_query in /etc/dovecot/dovecot-sql.conf.ext.iterate_attrs and iterate_filter in /etc/dovecot/dovecot-ldap.conf.ext.Checkpoint: ask for status using the same address or mask. If a wildcard returns nothing, inspect user database iteration before repeating the operation with a broader pattern.
Use replicate when an already-known replicator user should be processed immediately:
$ sudo doveadm replicator replicate '[email protected]'
$ sudo doveadm replicator status '[email protected]'For a wildcard, this command searches users that currently exist in the replicator, not the whole user database. The difference matters: add '*@example.net' discovers users through userdb, while replicate '*@example.net' searches the replicator's current list.
Choose a priority only when you have a reason to change scheduling:
$ sudo doveadm replicator replicate -p high '[email protected]'
$ sudo doveadm replicator replicate -p low '[email protected]'The only documented priority values are high and low. The -f option requests full replication for the selected user.
Warning: a full pass can create substantial network, storage and mailbox activity. Confirm the reason and monitor the result.
To see the status of currently running dsync processes, use:
$ sudo doveadm replicator dsync-status
...This reports active dsync work. It does not replace the per-user status check. Empty output can simply mean no dsync process is running at that instant. Run it again after starting a targeted replication, and use the user status to confirm the mailbox's resulting state.
Warning: remove changes the replicator's user list. It does not delete the mailbox, but it stops that user being managed by this replicator list. Verify the exact username before running it:
$ sudo doveadm replicator status '[email protected]'
$ sudo doveadm replicator remove '[email protected]'
$ sudo doveadm replicator status '[email protected]'Recovery: there is no undo flag in this command, so add the intended user again.
$ sudo doveadm replicator add '[email protected]'
$ sudo doveadm replicator status '[email protected]'If a batch command selected the wrong mask, stop issuing changes. Record the affected addresses from your logs or user database, then re-add only the intended users. Do not use a wildcard as a hurried recovery unless you have confirmed the user database iteration is correct.
Pass an absolute socket path with -a when the configured replicator socket is not the default:
$ sudo doveadm replicator status -a /run/dovecot/replicator-doveadm '[email protected]'The same option is available to add, remove, replicate and dsync-status. Do not guess a path or point at an arbitrary UNIX socket. Confirm it from the Dovecot configuration and filesystem permissions first.
For troubleshooting, add global -v for progress information or -D for debug messages. Keep debug output out of public tickets if it includes mailbox names or deployment details.
The -o setting=value option can override Dovecot settings for a command. You do not need it for the normal workflow, so use it only with a documented configuration change.
base_dir override.