man: Update kick/who/proxy man pages

diff --git a/doc/man/doveadm-kick.1.in b/doc/man/doveadm-kick.1.in
index 4bf10ed5b70cae6c5a377a2ed1265ce4065dd1c7..431b5da2690144733041c129db45ed4bd7557822 100644 (file)
--- a/doc/man/doveadm-kick.1.in
+++ b/doc/man/doveadm-kick.1.in
@@ -4,41 +4,65 @@
 doveadm\-kick \- Disconnect users by user name and/or IP address
 .\"------------------------------------------------------------------------
 .SH SYNOPSIS
-.BR doveadm " [" \-Dv "] " kick " [ \-a
+.BR doveadm " [" \-Dv "] " kick "
+.RB [ -a
 .IR anvil_socket_path ]
-.RB [ \-f ]
-.I user
+.RB [ \-f
+.IR passdb_field ]
+.RB [ \-h
+.IR dest_host ]
+.I user_mask
 .\"-------------------------------------
 .br
-.BR doveadm " [" \-Dv "] " kick " [ \-a
+.BR doveadm " [" \-Dv "] " kick "
+.RB [ -a
 .IR anvil_socket_path ]
-.RB [ \-f ]
-\fIip\fP[\fB/\fP\fImask\fP]
+.RB [ \-f
+.IR passdb_field ]
+.RB [ \-h
+.IR dest_host ]
+\fIip\fP[\fB/\fP\fIbits\fP]
 .\"-------------------------------------
 .br
-.BR doveadm " [" \-Dv "] " kick " [ \-a
+.BR doveadm " [" \-Dv "] " kick "
+.RB [ -a
 .IR anvil_socket_path ]
-.RB [ \-f ]
-.I user
-\fIip\fP[\fB/\fP\fImask\fP]
+.RB [ \-f
+.IR passdb_field ]
+.RB [ \-h
+.IR dest_host ]
+.I user_mask
+\fIip\fP[\fB/\fP\fIbits\fP]
+.\"-------------------------------------
+.br
+.BR doveadm " [" \-Dv "] " kick "
+.RB [ -a
+.IR anvil_socket_path ]
+.RB [ \-f
+.IR passdb_field ]
+.B \-h
+.I dest_host
 .\"------------------------------------------------------------------------
 .SH DESCRIPTION
 .BR doveadm \(aqs\  kick
 command is used to disconnect users by
-.I user
-name and/or the
+.I user_mask
+and/or the
 .I ip
 address, from which they are connected.
 .PP
 In the first form, all users, whose login name matches the
-.I user
+.I user_mask
 argument, will be disconnected.
 .PP
 In the second form, all users, connected from the given IP address or
 network range, will be disconnected.
 .PP
-In the last form, only users connected from the given IP address or
+In the third form, only users connected from the given IP address or
 networks range and a matching login name will be disconnected.
+.PP
+In the last form, all proxy connections to the given destination host are
+disconnected.
 .\"------------------------------------------------------------------------
 @INCLUDE:global-options@
 .\" --- command specific options --- "/.
@@ -61,35 +85,31 @@ setting was overridden in
 .IR @pkgsysconfdir@/dovecot.conf .
 .\"-------------------------------------
 .TP
-.B \-f
-Enforce the disconnect, even when there are multiple
-.IR user s,
-from different networks, connected to a single process.
-This option may be only required when you have configured something like:
-.sp
-.nf
-service imap {
-  ...
-  client_limit = \fI1+n\fP
-  service_count = 0
-  ...
-}
-.fi
+.BI \-f\  passdb_field
+Alternative username field to use for kicking, as returned by passdb.
+Only the passdb fields beginning with the
+.I user_
+prefix are tracked.
+.\"-------------------------------------
+.TP
+.BI \-h\  dest_host
+Disconnect proxy connections to the given
+.IR dest_host .
 .\"------------------------------------------------------------------------
 .SH ARGUMENTS
 .TP
-.IR ip [/ mask ]
+.IR ip [/ bits ]
 .I ip
 or
 .IB ip /\c
-.I mask
+.I bits
 is the host or network, from which the users are connected.
 .\"-------------------------------------
 .TP
-.I user
-Is a
-.IR user \(aqs
-login name.
+.I user_mask
+Is a user\(aqs login name, or the altenative username (user_* field) if the
+.B -f
+parameter is used.
 Depending on the configuration, a login name may be for example
 .BR jane " or " john@example.com .
 It\(aqs also possible to use
@@ -107,28 +127,27 @@ is 3 characters long and begins with
 .sp
 .nf
 .B doveadm who \-1 ja*
-username                      proto pid  ip
-jane                          imap  8192 ::1
-james                         imap  8203 2001:db8:543:2::1
-.B doveadm kick ba?
-kicked connections from the following users:
-bar baz
+username                      service pid ip
+jane                          imap   8192 ::1
+jano                          imap   8196 ::2
+james                         imap   8203 2001:db8:543:2::1
+.B doveadm kick jan?
+The connections for jane and jano are kicked.
 .fi
 .PP
 The next example shows how to kick user foo\(aqs connections from 192.0.2.*.
 .sp
 .nf
 .B doveadm who \-1 foo
-username                     proto pid  ip
-foo                          imap  8135 fd95:4eed:38ba::25
-foo                          imap  9112 192.0.2.53
-foo                          imap  8216 192.0.2.111
+username                     service pid ip
+foo                          imap   8135 fd95:4eed:38ba::25
+foo                          imap   9112 192.0.2.53
+foo                          imap   8216 192.0.2.111
 .B doveadm kick foo 192.0.2.0/24
-kicked connections from the following users:
-foo
+
 .B doveadm who f*
-username                  # proto (pids) (ips)
-foo                       1 imap  (8135) (fd95:4eed:38ba::25)
+username                  # service (pids) (ips)
+foo                       1 imap    (8135) (fd95:4eed:38ba::25)
 .fi
 .\"------------------------------------------------------------------------
 @INCLUDE:reporting-bugs@

diff --git a/doc/man/doveadm-proxy.1.in b/doc/man/doveadm-proxy.1.in
index c9aa70c8072dacbb362afbd51ef56b7610d7b8ce..e40078d41e2cbda75f0190f73eaeb18fe52f129f 100644 (file)
--- a/doc/man/doveadm-proxy.1.in
+++ b/doc/man/doveadm-proxy.1.in
@@ -1,85 +1,26 @@
 .\" Copyright (c) 2014-2018 Dovecot authors, see the included COPYING file
 .TH DOVEADM\-PROXY 1 "2014-11-09" "Dovecot v2.3" "Dovecot"
 .SH NAME
-doveadm\-proxy \- Handle Dovecot proxy connections
+doveadm\-proxy \- Handle Dovecot proxy connections (obsolete)
 .\"------------------------------------------------------------------------
 .SH SYNOPSIS
 .BR doveadm " [" \-Dv ]
 [\fB\-f\fP \fIformatter\fP]
-.BI proxy \ command
+.BI proxy \ kick
 .RI [ OPTIONS ]\ [ ARGUMENTS ]
-.\"------------------------------------------------------------------------
-.SH DESCRIPTION
-The
-.B doveadm proxy
-.I commands
-are used to list or kick active Dovecot proxy connections.
-.\"------------------------------------------------------------------------
-@INCLUDE:global-options-formatter@
-.\" --- command specific options --- "/.
-.PP
-This command uses by default the
-.B table
-output formatter.
-.PP
-Command specific
-.IR options :
-.\"-------------------------------------
-.TP
-.BI \-a \ ipc_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.
-.sp
-By default
-.BR doveadm (1)
-will use the socket
-.IR @rundir@/ipc .
-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 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 .
-It\(aqs also possible to use
-.RB \(dq * \(dq
-and
-.RB \(dq ? \(dq
-wildcards (e.g. *@example.org).
-.\"------------------------------------------------------------------------
-.SH COMMANDS
-.SS proxy kick
-.B doveadm proxy kick
-[\fB\-a\fP \fIipc_socket_path\fP]
-[\fB\-f\fP \fIpassdb_field\fP]
-[\fB\-h\fP \fIhost_list\fP | \fIuser_list\fP]
-.PP
-Kick all the connections being proxied for the given
-.IR user_list
-or for the given backend
-.IR host_list .
 .\"-------------------------------------
-.SS proxy list
-.B doveadm proxy list
-[\fB\-a\fP \fIipc_socket_path\fP]
-.PP
-List all the users currently being proxied.
+.br
+.BR doveadm " [" \-Dv ]
+[\fB\-f\fP \fIformatter\fP]
+.BI proxy \ list
+.RI [ OPTIONS ]\ [ ARGUMENTS ]
 .\"------------------------------------------------------------------------
-.SH EXAMPLE
-List all currently active proxy connections:
-.PP
-.nf
-.B doveadm proxy list
-username                    proto src ip          dest ip     port
-jane@example.net            imap  192.168.0.100   192.168.0.5 143
-.fi
+.SH DESCRIPTION
+These commands are aliases to the
+.B doveadm kick
+and 
+.B doveadm who
+commands.
 .\"------------------------------------------------------------------------
 @INCLUDE:reporting-bugs@
 .\"------------------------------------------------------------------------

diff --git a/doc/man/doveadm-who.1.in b/doc/man/doveadm-who.1.in
index 585580ba0b49015429b3b9c9874d064b6fc78f1f..f460d6570c82bcbe1e85108c1647c57411571ae0 100644 (file)
--- a/doc/man/doveadm-who.1.in
+++ b/doc/man/doveadm-who.1.in
@@ -7,9 +7,11 @@ doveadm\-who \- Show who is logged in to the Dovecot server
 .BR doveadm " [" \-Dv "] [" \-f
 .IR formatter ]
 .BR who\  [ \-1 ]
+.RB [ -f
+.IR passdb_field ]
 [\fB\-a\fP \fIanvil_socket_path\fP]
-.RI [ user ]
-[\fIip\fP[\fB/\fP\fImask\fP]]
+.RI [ user_mask ]
+[\fIip\fP[\fB/\fP\fIbits\fP]]
 .\"------------------------------------------------------------------------
 .SH DESCRIPTION
 The
@@ -47,19 +49,29 @@ The socket may be located in another directory, when the default
 .I base_dir
 setting was overridden in
 .IR @pkgsysconfdir@/dovecot.conf .
+.\"-------------------------------------
+.TP
+.BI \-f\  passdb_field
+Alternative username field to use for kicking, as returned by passdb.
+Only the passdb fields beginning with the
+.I user_
+prefix are tracked.
 .\"------------------------------------------------------------------------
 .SH ARGUMENTS
 .TP
-\fIip\fP[\fB/\fP\fImask\fP]
+\fIip\fP[\fB/\fP\fIbits\fP]
 Specify an
 .I ip
 address or network range, in CIDR notation, to reduce the result to
 matching connections.
 .\"-------------------------------------
 .TP
-.I user
-List only users, whose name match
-.IR user .
+.I user_mask
+List only users whose login name matches the
+.IR user_mask ,
+or the altenative username (user_* field) if the
+.B -f
+parameter is used.
 It\(aqs also possible to use wildcards in the
 .I user
 name.