1DOVEADM-DIRECTOR(1)                 Dovecot                DOVEADM-DIRECTOR(1)
2
3
4

NAME

6       doveadm-director - Manage Dovecot directors
7

SYNOPSIS

9       doveadm [-Dv] [-f formatter] director command [OPTIONS] [ARGUMENTS]
10

DESCRIPTION

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

OPTIONS

17       Global doveadm(1) options:
18
19       -D     Enables verbosity and debug messages.
20
21       -f formatter
22              Specifies  the  formatter  for formatting the output.  Supported
23              formatters are:
24
25              flow   prints each line with key=value pairs.
26
27              pager  prints each key: value pair on its own line and separates
28                     records with form feed character (^L).
29
30              tab    prints  a  table  header  followed by tab separated value
31                     lines.
32
33              table  prints a table header followed by adjusted value lines.
34
35       -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
41       -v     Enables verbosity, including progress counter.
42
43       Command specific options:
44
45       -a director_socket_path
46              This  option  is used to specify an alternative socket.  The op‐
47              tion's argument is either an absolute path to a local  UNIX  do‐
48              main socket, or a hostname and port (hostname:port), in order to
49              connect a remote host via a TCP socket.
50
51              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

ARGUMENTS

57       host   A mail server's hostname or IP address.
58
59       ip     A director's IP address.
60
61       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
65       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
68       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

COMMANDS

74   director add
75       doveadm director add [-a director_socket_path] host [vhost_count]
76
77       The command's tasks are:
78
79       *   assign a new mail server to the director.
80
81       *   increase/decrease the vhost_count of an already assigned server.
82
83   director dump
84       doveadm director dump [-a director_socket_path]
85
86       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
90   director flush
91       doveadm director flush [-a director_socket_path]  [-F]  [--max-parallel
92       n] host|all
93
94       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
99       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
104       If  the -F parameter is used, the user associations are simply dropped.
105       Existing connections won´t be kicked and flush scripts aren´t run.
106
107   director kick
108       doveadm director kick [-a director_socket_path] user
109
110       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
114   director map
115       doveadm director map [-a director_socket_path] [-f users_file]  [-h|-u]
116       [host]
117
118       The  command  doveadm  director map is used to list current userhost
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
123       -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
129       -h     Output all usernames, which match the given hash.
130
131       -u     Output hash for the given username.
132
133       host   Specify a server's IP address or hostname, to list only mappings
134              of the given host.
135
136   director move
137       doveadm director move [-a director_socket_path] user host
138
139       Move the user to the specified backend host.  If the user has  any  ex‐
140       isting connections they will be killed.
141
142   director remove
143       doveadm director remove [-a director_socket_path] host
144
145       Use this command in order to remove the given host from the director.
146
147   director ring add
148       doveadm director ring add [-a director_socket_path] ip [port]
149
150       Add a new director to the ring.
151
152   director ring remove
153       doveadm director ring remove [-a director_socket_path] ip [port]
154
155       Remove a director from the ring.
156
157   director ring status
158       doveadm director ring status [-a director_socket_path]
159
160       Show the status of all the directors currently in the ring.
161
162   director status
163       doveadm director status [-a director_socket_path] [user]
164
165       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

FILES

173       /etc/dovecot/dovecot.conf
174              Dovecot's main configuration file.
175
176       /etc/dovecot/conf.d/10-director.conf
177              Director specific settings.
178

EXAMPLE

180       Add  a  director  with  vhost count 150 (or change existing one's vhost
181       count to 150):
182
183       doveadm -v director add x1357.imap.ha.example.net 150
184       2001:db8:543:6861:143::1357: OK
185
186       Remove a director:
187
188       doveadm director remove x1357.imap.ha.example.net
189
190       Query the status of mail hosts in a director:
191
192       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
198       Query the status of a user's assignment:
199
200       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
205       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 as‐
207       signment will be removed (currently it looks like at 20:17:04, but that
208       may be increased). After the assignment has expired, the user will next
209       time be redirected to 192.168.10.2 (assuming  no  changes  to  director
210       settings).  If  the entire Dovecot proxy cluster was restarted, so that
211       all of the director configuration would revert back to its initial val‐
212       ues, the user would be redirected to 192.168.10.3.
213

REPORTING BUGS

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

SEE ALSO

220       doveadm(1)
221
222
223
224Dovecot v2.3                      2014-08-30               DOVEADM-DIRECTOR(1)
Impressum