diff options
Diffstat (limited to 'doc/man/doveadm-auth.1.in')
| -rw-r--r-- | doc/man/doveadm-auth.1.in | 216 |
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 |