From: Timo Sirainen Date: Wed, 2 Feb 2022 13:31:39 +0000 (+0200) Subject: man: Update kick/who/proxy man pages X-Git-Tag: 2.4.0~4469 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d4c6acf829deea4222b5e7f1eb25ec6f47ed13ac;p=thirdparty%2Fdovecot%2Fcore.git man: Update kick/who/proxy man pages --- diff --git a/doc/man/doveadm-kick.1.in b/doc/man/doveadm-kick.1.in index 4bf10ed5b7..431b5da269 100644 --- 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 c9aa70c807..e40078d41e 100644 --- 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 585580ba0b..f460d6570c 100644 --- 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.