1DOVEADM-DIRECTOR(1) Dovecot DOVEADM-DIRECTOR(1)
2
6 doveadm-director - Manage Dovecot directors
7
9 doveadm [-Dv] [-f formatter] director command [OPTIONS] [ARGUMENTS]
10
12 doveadm director can be used to manage and query the status of the list
13 of backend mail servers where Dovecot proxy can redirect connections
14 to.
15
17 Global doveadm(1) options:
18 -D Enables verbosity and debug messages.
20 -f formatter
22 Specifies the formatter for formatting the output. Supported
23 formatters are:
24 flow prints each line with key=value pairs.
26 pager prints each key: value pair on its own line and separates
28 records with form feed character (^L).
29 tab prints a table header followed by tab separated value
31 lines.
32 table prints a table header followed by adjusted value lines.
34 -o setting=value
36 Overrides the configuration setting from /etc/dovecot/dove‐
37 cot.conf and from the userdb with the given value. In order to
38 override multiple settings, the -o option may be specified mul‐
39 tiple times.
40 -v Enables verbosity, including progress counter.
42 Command specific options:
44 -a director_socket_path
46 This option is used to specify an alternative socket. The
47 option's argument is either an absolute path to a local UNIX
48 domain socket, or a hostname and port (hostname:port), in order
49 to connect a remote host via a TCP socket.
50 By default doveadm(1) will use the socket /run/dovecot/direc‐
52 tor-admin. The socket may be located in another directory, when
53 the default base_dir setting was overridden in /etc/dove‐
54 cot/dovecot.conf.
55
57 host A mail server's hostname or IP address.
58 ip A director's IP address.
60 port The TCP port, on which the director server is listening for con‐
62 nections. The default port is the same as what the local direc‐
63 tor is listening in.
64 user Is a user's login name. Depending on the configuration, a login
66 name may be for example jane or john@example.com.
67 vhost_count
69 The number of "virtual hosts" to assign to this server. The
70 higher the number is relative to other servers, the more connec‐
71 tions it gets. The default is 100.
72
74 director add
75 doveadm director add [-a director_socket_path] host [vhost_count]
76 The command's tasks are:
78 * assign a new mail server to the director.
80 * increase/decrease the vhost_count of an already assigned server.
82 director dump
84 doveadm director dump [-a director_socket_path]
85 Dump the current host configuration as doveadm commands. These commands
87 can be easily run after a full director cluster restart to get back to
88 the dumped state.
89 director flush
91 doveadm director flush [-a director_socket_path] [-f] [--max-parallel
92 n] host|all
93 doveadm director flush removes all user associations either from the
95 given host or all hosts. All the existing connections will be kicked.
96 If director_flush_socket is specified, a flush script is also automati‐
97 cally executed.
98 Because the kicking and moving of users to new backends creates a tem‐
100 porary load spike, all the users aren´t moved at once. The --max-paral‐
101 lel parameter specifies how many users can be moved concurrently. The
102 default is 100.
103 If -f parameter is used, the user associations are simply dropped.
105 Existing connections won´t be kicked and flush scripts aren´t run.
106 director kick
108 doveadm director kick [-a director_socket_path] user
109 Kick the specified user from the entire Dovecot cluster. This is simi‐
111 lar to doveadm proxy kick, but this command needs to be run only once
112 instead of in each director server.
113 director map
115 doveadm director map [-a director_socket_path] [-f users_file] [-h|-u]
116 [host]
117 The command doveadm director map is used to list current user → host
119 mappings. Note that the director works using 32bit hashes which makes
120 collisions quite likely, so this command can't reliably list exactly
121 which users have recently logged in.
122 -f users_file
124 Path to a file containing all user names (one per line). When
125 given no userdb lookup will be performed. This may be a helpful
126 alternative when for example the network connection to the LDAP
127 or SQL server is slow.
128 -h Output all usernames, which match the given hash.
130 -u Output hash for the given username.
132 host Specify a server's IP address or hostname, to list only mappings
134 of the given host.
135 director move
137 doveadm director move [-a director_socket_path] user host
138 Move the user to the specified backend host. If the user has any
140 existing connections they will be killed.
141 director remove
143 doveadm director remove [-a director_socket_path] host
144 Use this command in order to remove the given host from the director.
146 director ring add
148 doveadm director ring add [-a director_socket_path] ip [port]
149 Add a new director to the ring.
151 director ring remove
153 doveadm director ring remove [-a director_socket_path] ip [port]
154 Remove a director from the ring.
156 director ring status
158 doveadm director ring status [-a director_socket_path]
159 Show the status of all the directors currently in the ring.
161 director status
163 doveadm director status [-a director_socket_path] [user]
164 This command is used to show the current usage of all assigned mail
166 servers.
167 When a user name is given, this command shows which server the user is
168 currently assigned to, where the user will be assigned after the cur‐
169 rent saved assignment gets removed and where the user would be assigned
170 to if the whole proxy cluster was restarted fresh.
171
173 /etc/dovecot/dovecot.conf
174 Dovecot's main configuration file.
175 /etc/dovecot/conf.d/10-director.conf
177 Director specific settings.
178
180 Add a director with vhost count 150 (or change existing one's vhost
181 count to 150):
182 doveadm -v director add x1357.imap.ha.example.net 150
184 2001:db8:543:6861:143::1357: OK
185 Remove a director:
187 doveadm director remove x1357.imap.ha.example.net
189 Query the status of mail hosts in a director:
191 doveadm director status
193 mail server ip vhosts users
194 192.168.10.1 100 125
195 192.168.10.2 100 144
196 192.168.10.3 100 115
197 Query the status of a user's assignment:
199 doveadm director status user@example.com
201 Current: 192.168.10.1 (expires 2010-06-18 20:17:04)
202 Hashed: 192.168.10.2
203 Initial config: 192.168.10.3
204 This means that the user is currently assigned to mail server on IP
206 192.168.10.1. After all of user's connections have logged out, the
207 assignment will be removed (currently it looks like at 20:17:04, but
208 that may be increased). After the assignment has expired, the user will
209 next time be redirected to 192.168.10.2 (assuming no changes to direc‐
210 tor settings). If the entire Dovecot proxy cluster was restarted, so
211 that all of the director configuration would revert back to its initial
212 values, the user would be redirected to 192.168.10.3.
213
215 Report bugs, including doveconf -n output, to the Dovecot Mailing List
216 <dovecot@dovecot.org>. Information about reporting bugs is available
217 at: http://dovecot.org/bugreport.html
218
220 doveadm(1)
221Dovecot v2.3 2014-08-30 DOVEADM-DIRECTOR(1)