Adding upstream version 1:2.3.21+dfsg1.upstream/1%2.3.21+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 283 insertions, 0 deletions

diff --git a/doc/man/doveadm-director.1.in b/doc/man/doveadm-director.1.in
new file mode 100644
index 0000000..2a2c688
--- /dev/null
+++ b/doc/man/doveadm-director.1.in
@@ -0,0 +1,283 @@
+.\" Copyright (c) 2013-2018 Dovecot authors, see the included COPYING file
+.TH DOVEADM\-DIRECTOR 1 "2014-08-30" "Dovecot v2.3" "Dovecot"
+.SH NAME
+doveadm\-director \- Manage Dovecot directors
+.\"------------------------------------------------------------------------
+.SH SYNOPSIS
+.BR doveadm " [" \-Dv ]
+[\fB\-f\fP \fIformatter\fP]
+.BI director \ command
+.RI [ OPTIONS ]\ [ ARGUMENTS ]
+.\"------------------------------------------------------------------------
+.SH DESCRIPTION
+.B 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.
+.\"------------------------------------------------------------------------
+@INCLUDE:global-options-formatter@
+.\" --- command specific options --- "/.
+.PP
+Command specific
+.IR options :
+.\"-------------------------------------
+.TP
+.BI \-a\  director_socket_path
+This option is used to specify an alternative socket.
+The option\(aqs argument is either an absolute path to a local UNIX domain
+socket, or a hostname and port
+.RI ( hostname : port ),
+in order to connect a remote host via a TCP socket.
+.sp
+By default
+.BR doveadm (1)
+will use the socket
+.IR @rundir@/director\-admin .
+The socket may be located in another directory, when the default
+.I base_dir
+setting was overridden in
+.IR @pkgsysconfdir@/dovecot.conf .
+.\"------------------------------------------------------------------------
+.SH ARGUMENTS
+.TP
+.I host
+A mail server\(aqs hostname or IP address.
+.\"-------------------------------------
+.TP
+.I ip
+A director\(aqs IP address.
+.\"-------------------------------------
+.TP
+.I 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.
+.\"-------------------------------------
+.TP
+.I user
+Is a
+.IR user \(aqs
+login name.
+Depending on the configuration, a login name may be for example
+.BR jane " or " john@example.com .
+.\"-------------------------------------
+.TP
+.I vhost_count
+The number of \(dqvirtual hosts\(dq to assign to this server. The higher
+the number is relative to other servers, the more connections it gets. The
+default is 100.
+.\"------------------------------------------------------------------------
+.SH COMMANDS
+.SS director add
+.B doveadm director add
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.I host
+.RI [ vhost_count ]
+.PP
+The command\(aqs tasks are:
+.TP 4
+*
+assign a new mail server to the director.
+.TP
+*
+increase/decrease the
+.I vhost_count
+of an already assigned server.
+.PP
+.\"-------------------------------------
+.SS director dump
+.B doveadm director dump
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.PP
+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.
+.\"-------------------------------------
+.SS director flush
+.B doveadm director flush
+[\fB\-a\fP \fIdirector_socket_path\fP]
+[\fB\-F\fP]
+[\fB\-\-max\-parallel\fP \fIn\fP]
+\fIhost\fP|\fBall\fP
+.PP
+.B doveadm director flush
+removes all user associations either from the given
+.I host
+or
+.B all
+hosts. All the existing connections will be kicked. If
+.B director_flush_socket
+is specified, a flush script is also automatically executed.
+.PP
+Because the kicking and moving of users to new backends creates a temporary
+load spike, all the users aren\'t moved at once. The
+.B \-\-max\-parallel
+parameter specifies how many users can be moved concurrently.
+The default is 100.
+.PP
+If the
+.B \-F
+parameter is used, the user associations are simply dropped. Existing
+connections won\'t be kicked and flush scripts aren\'t run.
+.\"-------------------------------------
+.SS director kick
+.B doveadm director kick
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.I user
+.PP
+Kick the specified
+.I user
+from the entire Dovecot cluster.
+This is similar to doveadm proxy kick, but this command needs to be run
+only once instead of in each director server.
+.\"-------------------------------------
+.SS director map
+.B doveadm director map
+[\fB\-a\fP \fIdirector_socket_path\fP]
+[\fB\-f\fP \fIusers_file\fP]
+[\fB\-h\fP|\fB\-u\fP]
+.RI [ host ]
+.PP
+The command
+.B doveadm director map
+is used to list current
+.IR user "\ \(->\ " host
+mappings. Note that the director works using 32bit hashes which makes
+collisions quite likely, so this command can\(aqt reliably list exactly
+which users have recently logged in.
+.PP
+.TP
+.BI \-f\  users_file
+Path to a file containing all user names (one per line).
+When given no
+.I 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.
+.\"-----------------
+.TP
+.B \-h
+Output all usernames, which match the given hash.
+.\"-----------------
+.TP
+.B \-u
+Output hash for the given username.
+.\"-----------------
+.TP
+.I host
+Specify a server\(aqs IP address or hostname, to list only mappings of the
+given
+.IR host .
+.\"-------------------------------------
+.SS director move
+.B doveadm director move
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.I user host
+.PP
+Move the
+.I user
+to the specified backend
+.IR host .
+If the
+.I user
+has any existing connections they will be killed.
+.\"-------------------------------------
+.SS director remove
+.B doveadm director remove
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.I host
+.PP
+Use this command in order to remove the given
+.I host
+from the director.
+.\"-------------------------------------
+.SS director ring add
+.B doveadm director ring add
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.IR ip \ [ port ]
+.PP
+Add a new director to the ring.
+.\"-------------------------------------
+.SS director ring remove
+.B doveadm director ring remove
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.IR ip \ [ port ]
+.PP
+Remove a director from the ring.
+.\"-------------------------------------
+.SS director ring status
+.B doveadm director ring status
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.PP
+Show the status of all the directors currently in the ring.
+.\"-------------------------------------
+.SS director status
+.B doveadm director status
+[\fB\-a\fP \fIdirector_socket_path\fP]
+.RI [ user ]
+.PP
+This command is used to show the current usage of all assigned mail
+servers.
+.br
+When a user name is given, this command shows which server the
+.I 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.
+.\"------------------------------------------------------------------------
+.SH FILES
+.TP
+.I @pkgsysconfdir@/dovecot.conf
+Dovecot\(aqs main configuration file.
+.TP
+.I @pkgsysconfdir@/conf.d/10\-director.conf
+Director specific settings.
+.\"------------------------------------------------------------------------
+.SH EXAMPLE
+Add a director with vhost count 150 (or change existing one\(aqs
+vhost count to 150):
+.PP
+.nf
+.B doveadm \-v director add x1357.imap.ha.example.net 150
+2001:db8:543:6861:143::1357: OK
+.fi
+.\"-------------------------------------
+.PP
+Remove a director:
+.PP
+.nf
+.B doveadm director remove x1357.imap.ha.example.net
+.fi
+.\"-------------------------------------
+.PP
+Query the status of mail hosts in a director:
+.PP
+.nf
+.B 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
+.fi
+.\"-------------------------------------
+.PP
+Query the status of a user\(aqs assignment:
+.PP
+.nf
+.B 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
+.fi
+.PP
+This means that the user is currently assigned to mail server on IP
+192.168.10.1. After all of user\(aqs connections 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 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 values, the
+user would be redirected to 192.168.10.3.
+.\"------------------------------------------------------------------------
+@INCLUDE:reporting-bugs@
+.\"------------------------------------------------------------------------
+.SH SEE ALSO
+.BR doveadm (1)
\ No newline at end of file