Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DOVEADM-DIRECTOR(1)		    Dovecot		   DOVEADM-DIRECTOR(1)

NAME
       doveadm-director	- Manage Dovecot directors

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

DESCRIPTION
       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.

OPTIONS
       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  /usr/local/etc/dove-
	      cot/dovecot.conf	and  from the userdb with the given value.  In
	      order to override	multiple settings, the -o option may be	speci-
	      fied 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 op-
	      tion's argument is either	an absolute path to a local  UNIX  do-
	      main 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/di-
	      rector-admin.   The  socket may be located in another directory,
	      when the default base_dir	setting	 was  overridden  in  /usr/lo-
	      cal/etc/dovecot/dovecot.conf.

ARGUMENTS
       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 con-
	      nections.	 The default port is the same as what the local	direc-
	      tor is listening in.

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

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

COMMANDS
   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 automati-
       cally executed.

       Because the kicking and moving of users to new backends creates a  tem-
       porary load spike, all the users	aren't moved at	once. The --max-paral-
       lel parameter specifies how many	users can be moved concurrently.   The
       default is 100.

       If  -f parameter	is used, the user associations are simply dropped. Ex-
       isting 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 simi-
       lar  to	doveadm	proxy kick, but	this command 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 slow.

       -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  ex-
       isting 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 cur-
       rent saved assignment gets removed and where the	user would be assigned
       to if the whole proxy cluster was restarted fresh.

FILES
       /usr/local/etc/dovecot/dovecot.conf
	      Dovecot's	main configuration file.

       /usr/local/etc/dovecot/conf.d/10-director.conf
	      Director specific	settings.

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

       doveadm -v director add x1357.imap.ha.example.net 150
       2001:db8:543:6861:143::1357: OK

       Remove a	director:

       doveadm director	remove x1357.imap.ha.example.net

       Query the status	of mail	hosts in a director:

       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

       Query the status	of a user's assignment:

       doveadm director	status user@example.com
       Current:	192.168.10.1 (expires 2010-06-18 20:17:04)
       Hashed: 192.168.10.2
       Initial config: 192.168.10.3

       This means that the user	is currently assigned to  mail	server	on  IP
       192.168.10.1.  After all	of user's connections have logged out, the as-
       signment	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 192.168.10.2 (assuming  no	 changes  to  director
       settings).  If  the entire Dovecot proxy	cluster	was restarted, so that
       all of the director configuration would revert back to its initial val-
       ues, the	user would be redirected to 192.168.10.3.

REPORTING BUGS
       Report  bugs, including doveconf	-n output, to the Dovecot Mailing List
       <dovecot@dovecot.org>.  Information about reporting bugs	 is  available
       at: http://dovecot.org/bugreport.html

SEE ALSO
       doveadm(1)

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

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ARGUMENTS | COMMANDS | FILES | EXAMPLE | REPORTING BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=doveadm-director&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help