Move Older dbox Mail to Alternative Storage with doveadm altmove

You will finish with a controlled way to move matching messages from Dovecot dbox storage to an alternative path, then move them back if necessary. The examples target the locally installed Dovecot package, dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5, whose installed manual describes the Dovecot v2.3 interface.

Allow 20 to 30 minutes for a first run. You need access to the Dovecot host, a working sdbox or mdbox mailbox, an alternative filesystem mounted at its final path, and permission to run administrative doveadm commands. This changes message storage, so take a mailbox backup or snapshot before testing a production account.

1. Check that alternative storage is actually configured

doveadm altmove is for dbox storage only. It does not turn an ordinary Maildir into dbox storage, and it does not choose an alternative path for you. In the Dovecot 2.3 configuration style, the ALT= component of mail_location supplies that path:

mail_location = mdbox:~/mdbox:ALT=/nfsmount/%h/mdbox

Here ~/mdbox is the normal location and /nfsmount/%h/mdbox is the alternative location. The exact path and variable expansion belong to your existing configuration. Do not paste this line into production merely because the example uses it.

Inspect the effective configuration as an ordinary read-only check. This command may need elevated privileges on a host where Dovecot's configuration is not readable by your account:

$ sudo doveconf -n | grep -E '^(mail_location|mail_driver|mail_path|mail_alt_path)'

On newer Dovecot documentation, the same idea is expressed with separate mail_driver, mail_path and mail_alt_path settings. Do not mix that newer configuration model into a 2.3 host without checking that host's own documentation and configuration parser.

2. Start with one user and a narrow search

The command moves every message matching its search query. There is no dry-run option in the installed doveadm-altmove(1) interface, so begin with one account and a deliberately small, reviewable query. The following is the documented shape for messages seen more than one week ago:

$ sudo doveadm altmove -u '[email protected]' seen savedbefore 1w

-u limits the operation to the named user. The words after the user are the search query, not shell options. They are interpreted by Dovecot's search-query language. Quote a username or wildcard when the shell could expand it; -u '*@example.com', for example, asks Dovecot to match users at that domain.

The command normally produces little or no output unless verbosity is enabled. Add -v when you need a progress counter, or -D for debug messages:

$ sudo doveadm -v altmove -u '[email protected]' seen savedbefore 1w

Do not treat a clean return as proof that the intended messages were selected. Before a production move, run the equivalent search with a non-mutating mailbox inspection method available in your Dovecot tooling, record the matching count, and check the query against a test account. The altmove command itself has no count-only mode documented here.

3. Move the selected data to the alternative path

After the path, mount and query have been checked, run the narrow command as the account that is authorised to administer Dovecot. On many installations that means root, as shown below:

$ sudo doveadm altmove -v -u '[email protected]' seen savedbefore 1w
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the command completed successfully. It does not print a portable list of moved message files, and the exact progress output is version and workload dependent. The message remains part of the mailbox: only its dbox message data is moved. Dovecot's dbox documentation explains that indexes and other mailbox metadata remain in the primary location.

For mdbox, several messages can share one storage file. Dovecot can rewrite the data into an alternative storage file and update the map so that individual messages move without requiring you to manipulate dbox files by hand. Do not use cp or mv on those files as an improvised substitute; the mailbox metadata updates must be coordinated.

4. Verify both mailbox access and the storage location

First verify the command and service still see the mailbox. Use the same narrow search with a read-only mailbox listing or search command available on your host, and confirm that the message is still visible to the user. A message being absent from the primary directory alone is not a failure: that is the intended result after a successful move.

Then inspect the configured alternative tree with filesystem tools. The exact expanded path depends on your Dovecot variables, so substitute the real path rather than copying the placeholder:

$ sudo find '/nfsmount/EXPANDED-USER-PATH/mdbox' -maxdepth 1 -type f -printf '%f\n' | head
$ sudo df -h '/nfsmount/EXPANDED-USER-PATH/mdbox'

These commands show that the mount is reachable and contains storage files, not that a particular message is in a particular file. dbox filenames and packing vary. The useful application-level check is that Dovecot can still open the mailbox and return the moved message through its normal search and delivery path.

5. Reverse the move when the primary path is ready

The -r option changes direction: matching messages are moved from alternative storage back to the default location. Keep the same user restriction and query while recovering or testing:

$ sudo doveadm -v altmove -r -u '[email protected]' seen savedbefore 1w
$ printf 'exit status: %s\n' "$?"
exit status: 0

This is the practical undo for messages selected by the original query, provided the alternative storage is still reachable and the primary storage has enough space. It is not a general rollback log. If the original query now matches a different set of messages, the reverse command will act on that different set, so record the account and query used for every change.

Do not delete the alternative files manually after reversing a move. Let Dovecot complete its storage and map updates, then verify mailbox access and available space on both paths.

6. Scale out only after the single-user run is sound

-A runs the command for all users discovered through the user database. That discovery depends on the user database's iteration settings. The manual specifically warns about system users below first_valid_uid, and it requires matching iterate_query for SQL or iterate_attrs and iterate_filter for LDAP. A bad iteration configuration can omit users or include accounts you did not intend to touch.

$ sudo doveadm -v altmove -A seen savedbefore 1w

Use -F when an explicit file is safer than user database iteration. The file contains one username per line:

$ sudo doveadm -v altmove -F /root/dovecot-altmove-users.txt seen savedbefore 1w

Build and review that file separately, protect it from unwanted edits, and keep it as the audit record for the run. Both forms remain destructive storage changes. Schedule them only after you have monitored a single-user run, checked mount capacity and agreed how to recover a partial operation.