Man Pages

doveadm-director(1) - phpMan doveadm-director(1) - phpMan

Command: man perldoc info search(apropos)  

DOVEADM-DIRECTOR(1)                 Dovecot                DOVEADM-DIRECTOR(1)

       doveadm-director - Manage Dovecot directors

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

       doveadm  director  can be used to manage and query the status of the list of backend mail servers where Dovecot
       proxy can redirect connections to.

       Global doveadm(1) options:

       -D     Enables verbosity and debug messages.

       -f formatter
              Specifies the formatter for formatting the output.  Supported formatters are:

              flow   prints each line with key=value pairs.

              pager  prints each key: value pair on its own line and separates records with form feed character  (^L).

              tab    prints a table header followed by tab separated value lines.

              table  prints a table header followed by adjusted value lines.

       -o setting=value
              Overrides  the  configuration  setting from /etc/dovecot/dovecot.conf and from the userdb with the given
              value.  In order to override multiple settings, the -o option may be specified multiple times.

       -v     Enables verbosity, including progress counter.

       Command specific options:

       -a director_socket_path
              This option is used to specify an alternative socket.  The option's argument is either an absolute  path
              to a local UNIX domain socket, or a hostname and port (hostname:port), in order to connect a remote host
              via a TCP socket.

              By default doveadm(1) will use the socket /var/run/dovecot/director-admin.  The socket may be located in
              another directory, when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf.

       host   A mail server's hostname or IP address.

       ip     A director's IP address.

       port   The  TCP  port, on which the director server is listening for connections.  The default port is the same
              as what the local director is listening in.

       user   Is a user's login name.  Depending on the configuration, a  login  name  may  be  for  example  jane  or

              The  number  of  "virtual  hosts"  to  assign to this server. The higher the number is relative to other
              servers, the more connections it gets. The default is 100.

   director add
       doveadm director add [-a director_socket_path] host [vhost_count]

       The command's tasks are:

       *   assign a new mail server to the director.

       *   increase/decrease the vhost_count of an already assigned server.

   director dump
       doveadm director dump [-a director_socket_path]

       Dump the current host configuration as doveadm commands. These commands can be easily run after a full director
       cluster restart to get back to the dumped state.

   director flush
       doveadm director flush [-a director_socket_path] [-f] [--max-parallel n] host|all

       doveadm  director flush removes all user associations either from the given host or all hosts. All the existing
       connections will be kicked. If director_flush_socket is specified, a flush script is  also  automatically  exe-

       Because  the  kicking  and moving of users to new backends creates a temporary load spike, all the users aren?t
       moved at once. The --max-parallel parameter specifies how many users can be moved concurrently.  The default is

       If  -f  parameter  is  used, the user associations are simply dropped. Existing connections won?t be kicked and
       flush scripts aren?t run.

   director kick
       doveadm director kick [-a director_socket_path] user

       Kick the specified user from the entire Dovecot cluster.  This is similar to doveadm proxy kick, but this  com-
       mand needs to be run only once instead of in each director server.

   director map
       doveadm director map [-a director_socket_path] [-f users_file] [-h|-u] [host]

       The  command  doveadm  director  map is used to list current user -> host mappings. Note that the director works
       using 32bit hashes which makes collisions quite likely, so this command can't reliably list exactly which users
       have recently logged in.

       -f users_file
              Path to a file containing all user names (one per line).  When given no userdb lookup will be performed.
              This may be a helpful alternative when for example the network connection to the LDAP or SQL  server  is

       -h     Output all usernames, which match the given hash.

       -u     Output hash for the given username.

       host   Specify a server's IP address or hostname, to list only mappings of the given host.

   director move
       doveadm director move [-a director_socket_path] user host

       Move the user to the specified backend host.  If the user has any existing connections they will be killed.

   director remove
       doveadm director remove [-a director_socket_path] host

       Use this command in order to remove the given host from the director.

   director ring add
       doveadm director ring add [-a director_socket_path] ip [port]

       Add a new director to the ring.

   director ring remove
       doveadm director ring remove [-a director_socket_path] ip [port]

       Remove a director from the ring.

   director ring status
       doveadm director ring status [-a director_socket_path]

       Show the status of all the directors currently in the ring.

   director status
       doveadm director status [-a director_socket_path] [user]

       This command is used to show the current usage of all assigned mail servers.
       When  a  user  name is given, this command shows which server the user is currently assigned to, where the user
       will be assigned after the current saved assignment gets removed and where the user would be assigned to if the
       whole proxy cluster was restarted fresh.

              Dovecot's main configuration file.

              Director specific settings.

       Add a director with vhost count 150 (or change existing one's vhost count to 150):

       doveadm -v director add 150
       2001:db8:543:6861:143::1357: OK

       Remove a director:

       doveadm director remove

       Query the status of mail hosts in a director:

       doveadm director status
       mail server ip       vhosts  users            100    125            100    144            100    115

       Query the status of a user's assignment:

       doveadm director status
       Current: (expires 2010-06-18 20:17:04)
       Initial config:

       This  means  that the user is currently assigned to mail server on IP After all of user's connec-
       tions have logged out, the assignment will be removed (currently it looks like at 20:17:04,  but  that  may  be
       increased).  After  the assignment has expired, the user will next time be redirected to (assuming
       no changes to director settings). If the entire Dovecot proxy cluster was restarted, so that all of the  direc-
       tor configuration would revert back to its initial values, the user would be redirected to

       Report  bugs,  including  doveconf  -n  output, to the Dovecot Mailing List <>.  Information
       about reporting bugs is available at:


Dovecot v2.2                      2014-08-30               DOVEADM-DIRECTOR(1)