Drain and Weight Dovecot Backends with doveadm director

Use doveadm director to see where Dovecot is sending each user, then reweight or drain a backend without a surprise outage. A read-only check takes about 20 minutes, longer if you are changing production traffic.

You will inspect the director, see where a user is assigned, change a backend's share of new connections, and drain a backend in a controlled way. The examples use the installed dovecot-core package, version 1:2.3.21+dfsg1-2ubuntu6.5, and the local doveadm-director(1) manual page describes Dovecot v2.3 behaviour.

• Safe to run: status, map, ring status and dump are normally read-only for an operator with access to the director socket.
• Not safe to run casually: adding, removing, flushing, moving or changing a backend can affect users immediately.
• No automatic sudo. Use the account your Dovecot installation requires. The socket permissions are part of the deployment's access control.

1. Confirm the command and socket

Start by checking which binary and package you are about to use:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm director
usage: doveadm [-Dv] [-f <formatter>] director <command> ...

The local manual gives /run/dovecot/director-admin as the default admin socket. A different base_dir can place it elsewhere. Use -a with an absolute UNIX socket path, or with HOSTNAME:PORT for a TCP director socket:

$ doveadm director -a /run/dovecot/director-admin status

2. Record the current director state

Run the read-only status commands before changing anything:

$ doveadm director status
mail server ip       vhosts  users
192.168.10.1            100    125
192.168.10.2            100    144
192.168.10.3            100    115
$ doveadm director ring status
director ip     port  type  last failed  status
192.168.10.10   9090  self  never        synced

Your rows will differ. Here is how to read them:

• Status shows the assigned mail servers, their virtual-host counts and current users.
• Ring status shows director peers. A healthy peer normally reaches synced.
• Dump (doveadm director dump) prints the current host configuration as doveadm commands that can restore the state after a full director-cluster restart.

Save the status output in your change record, and save the dump to a file:

$ doveadm director dump > director-state-before.txt
$ test -s director-state-before.txt && echo 'state dump saved'
state dump saved

3. Check one user's assignment

Use the exact login name understood by your user database:

$ doveadm director status [email protected]
Current: 192.168.10.1 (expires 2030-06-18 20:17:04)
Hashed: 192.168.10.2
Initial config: 192.168.10.3

The names and timestamps are examples of the documented fields, not values to expect literally. Read the three lines like this:

• Current is the live assignment while connections remain.
• Hashed is where the user would go after the saved assignment expires, assuming the director state stays unchanged.
• Initial config is the result after the proxy cluster returns to its initial configuration.

The common mistake is treating the hashed destination as proof that existing connections have already moved. They have not.

To inspect mappings rather than one user, use:

$ doveadm director map 192.168.10.1
[email protected] 192.168.10.1

4. Add a backend or change its weight

The vhost_count controls the backend's relative share of new assignments. The documented default is 100. Adding a host that already exists changes its count, so check the spelling and current status first:

$ doveadm director add mail04.example.net 150
$ doveadm director status
mail server ip       vhosts  users
mail04.example.net       150      0

A higher count gives a backend more virtual hosts relative to its peers. It is a weighting mechanism, not a fixed user limit.

There is no separate undo operation for this example. Restore the previous count explicitly, then verify:

$ doveadm director add mail04.example.net 100
$ doveadm director status

5. Drain a backend carefully

Before maintenance, stop new assignments by setting the backend's count to zero with the management method used by your installed Dovecot, then confirm the status. On the local binary, the command list includes update:

$ doveadm director update mail04.example.net 0
$ doveadm director status
mail04.example.net         0     87

The local v2.3 manpage documents the equivalent operational idea through add, which changes an existing host's count. Prefer the syntax exposed by doveadm director on the machine you are operating, and test it during a maintenance window. A zero count does not remove existing assignments by itself.

To move users away, run the documented flush command:

$ doveadm director flush --max-parallel 25 mail04.example.net
$ doveadm director status
mail04.example.net         0      0

The default maximum parallelism is 100. A smaller value reduces the temporary load spike but takes longer. If the backend must return, set its count back to its previous value and confirm that the service and director ring are healthy before allowing traffic.

6. Move or remove with a recovery path

For one known user, move changes the assignment and kills that user's existing connections:

$ doveadm director move [email protected] mail02.example.net
$ doveadm director status [email protected]

Use this for a targeted repair, not as a substitute for draining a host. To remove a backend permanently, follow this order:

1. Weight it to zero.
2. Flush its users.
3. Confirm the count is zero.
4. Then remove it, as below.

$ doveadm director remove mail04.example.net
$ doveadm director status
mail server ip       vhosts  users