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, 216 insertions, 0 deletions

diff --git a/doc/man/doveadm-auth.1.in b/doc/man/doveadm-auth.1.in
new file mode 100644
index 0000000..f70bfda
--- /dev/null
+++ b/doc/man/doveadm-auth.1.in
@@ -0,0 +1,216 @@
+.\" Copyright (c) 2010-2018 Dovecot authors, see the included COPYING file
+.TH DOVEADM\-AUTH 1 "2014-10-19" "Dovecot v2.3" "Dovecot"
+.SH NAME
+doveadm\-auth \- Flush/lookup/test authentication data
+.\"------------------------------------------------------------------------
+.SH SYNOPSIS
+.BR doveadm " [" \-Dv ]
+[\fB\-f\fP \fIformatter\fP]
+.BI auth \ command
+.RI [ OPTIONS ]\ [ ARGUMENTS ]
+.\"------------------------------------------------------------------------
+.SH DESCRIPTION
+The
+.B doveadm \ auth
+.I COMMANDS
+can be used to perform various authentication related actions.
+.\"------------------------------------------------------------------------
+@INCLUDE:global-options-formatter@
+.\" --- command specific options --- "/.
+.PP
+Command specific
+.IR options :
+.\"-------------------------------------
+.TP
+.BI \-x\  auth_info
+.I auth_info
+specifies additional conditions for the
+.BR "auth lookup" " and " "auth test"
+commands.
+The
+.I auth_info
+option string has to be given as
+.IB name = value
+pair.
+For multiple conditions the
+.B \-x
+option could be supplied multiple times.
+.br
+All the given fields are forwarded to the auth process without checking for
+their validity. The important names for the
+.I auth_info
+are:
+.RS
+.TP
+.B service
+The service for which the authentication lookup should be tested.
+The value may be the name of a service, commonly used with Dovecot.
+For example:
+.BR imap ,
+.BR pop3\  or
+.BR smtp .
+.TP
+.B lip
+The local IP address (server) for the test.
+.TP
+.B rip
+The remote IP address (client) for the test.
+.TP
+.B lport
+The local port, e.g. 143
+.TP
+.B rport
+The remote port, e.g. 24567
+.TP
+.B real_lip
+The "real" local IP address (server) for the test. This is intended to be the
+local server\(aqs IP, while "lip" contains the connecting proxy server\(aqs
+local IP.
+.TP
+.B real_rip
+The "real" remote IP address (client) for the test. This is intended to be the
+connecting proxy server\(aqs IP address, while "rip" contains the original
+client\(aqs IP.
+.TP
+.B real_lport
+The "real" local port for proxied connections.
+.TP
+.B real_rport
+The "real" remote port for proxied connections.
+.TP
+.B local_name
+Provide the client TLS connection\(aqs SNI name.
+.TP
+.B client_id
+IMAP client ID string.
+.TP
+.B session
+Session ID string, mainly for logging purposes.
+.RE
+.\"------------------------------------------------------------------------
+.SH ARGUMENTS
+.\"-------------------------------------
+.TP
+.I user
+The
+.IR user \(aqs
+login name.
+Depending on the configuration, the login name may be for example
+.BR jane " or " john@example.com .
+.\"-------------------------------------
+.TP
+.I password
+Optionally the user\(aqs password.
+.BR doveadm (1)
+will prompt for the password, if none was given.
+.\"------------------------------------------------------------------------
+.SH COMMANDS
+.SS auth cache flush
+.B doveadm auth cache flush
+.RB [ \-a
+.IR master_socket_path ]
+.RI [ user " ...]"
+.PP
+Flush the authentication cache.
+By default the cache is flushed for all the users (which can also be done
+by sending SIGHUP to the auth process).
+You can also flush the cache for one or more users by providing their
+usernames.
+.PP
+.TP
+.BI \-a \ master_socket_path
+This option is used to specify an absolute path to an alternative UNIX
+domain socket.
+.sp
+By default
+.BR doveadm (1)
+will use the socket
+.IR @rundir@/auth\-master .
+The socket may be located in another directory, when the default
+.I base_dir
+setting was overridden in
+.IR @pkgsysconfdir@/dovecot.conf .
+.\"-------------------------------------
+.SS auth lookup
+.B doveadm auth lookup
+.RB [ \-a
+.IR userdb_socket_path ]
+.RB [ \-x
+.IR auth_info ]
+.RB [ \-f
+.IR field ] \ user \ [...]
+.PP
+Similar to
+.BR doveadm\-user (1)
+command, except it performs a
+.I passdb
+lookup (without authentication) instead of a
+.I userdb
+lookup.
+.PP
+.TP
+.BI \-a \ userdb_socket_path
+This option is used to specify an absolute path to an alternative UNIX
+domain socket.
+.sp
+By default
+.BR doveadm (1)
+will use the socket
+.IR @rundir@/auth\-userdb .
+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 \ field
+When this option and the name of a userdb field is given,
+.BR doveadm (1)
+will show only the value of the specified field.
+.\"-------------------------------------
+.SS auth test
+.B doveadm auth test
+.RB [ \-a
+.IR auth_socket_path ]
+.RB [ \-x
+.IR auth_info ]
+.IR user \ [ password ]
+.PP
+Test authentication for the given user.
+.\"-------------------------------------
+.TP
+.BI \-a\  auth_socket_path
+This option is used to specify an absolute path to an alternative UNIX
+domain socket.
+.sp
+By default
+.BR doveadm (1)
+will use the socket
+.IR @rundir@/auth\-client .
+The socket may be located in another directory, when the default
+.I base_dir
+setting was overridden in
+.IR @pkgsysconfdir@/dovecot.conf .
+
+.\"------------------------------------------------------------------------
+.SH EXAMPLE
+This example demonstrates an imap authentication test for user john,
+assuming the user is connected from the host with the IP address
+192.0.2.143.
+.PP
+.nf
+.ft B
+doveadm auth test \-x service=imap \-x rip=192.0.2.143 john
+.ft P
+Password:
+passdb: john auth succeeded
+extra fields:
+  user=john
+.fi
+.\"------------------------------------------------------------------------
+@INCLUDE:reporting-bugs@
+.\"------------------------------------------------------------------------
+.SH SEE ALSO
+.BR doveadm (1),
+.BR doveadm\-user (1),
+.BR doveconf (1)
\ No newline at end of file