dovecot-2.2: man: doveadm-auth man page updated

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.2/rev/03653943b6ad
changeset: 17784:03653943b6ad
user:      Pascal Volk <user at localhost.localdomain.org>
date:      Wed Sep 10 14:42:34 2014 +0300
description:
man: doveadm-auth man page updated

diffstat:

 doc/man/doveadm-auth.1.in |  134 ++++++++++++++++++++++++++++++++++++---------
 1 files changed, 105 insertions(+), 29 deletions(-)

diffs (176 lines):

diff -r 6848068151bf -r 03653943b6ad doc/man/doveadm-auth.1.in
--- a/doc/man/doveadm-auth.1.in	Wed Sep 10 14:37:50 2014 +0300
+++ b/doc/man/doveadm-auth.1.in	Wed Sep 10 14:42:34 2014 +0300
@@ -1,47 +1,32 @@
-.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file
-.TH DOVEADM\-AUTH 1 "2010-06-09" "Dovecot v2.2" "Dovecot"
+.\" Copyright (c) 2010-2014 Dovecot authors, see the included COPYING file
+.TH DOVEADM\-AUTH 1 "2014-08-30" "Dovecot v2.2" "Dovecot"
 .SH NAME
-doveadm\-auth \- Test authentication for a user
+doveadm\-auth \- Flush/lookup/test authentication data
 .\"------------------------------------------------------------------------
 .SH SYNOPSIS
-.BR doveadm " [" \-Dv "] " auth
-[\fB\-a\fP \fIauth_socket_path\fP]
-[\fB\-x\fP \fIauth_info\fP]
-.I user
-[\fIpassword\fP]
+.BR doveadm " [" \-Dv ]
+[\fB\-f\fP \fIformatter\fP]
+.BI auth \ command
+.RI [ OPTIONS ]\ [ ARGUMENTS ]
 .\"------------------------------------------------------------------------
 .SH DESCRIPTION
 The
-.B auth
-command can be used to test the authentication for the given
-.IR user .
+.B doveadm \ auth
+.I COMMANDS
+can be used to perform various authentication related actions.
 .\"------------------------------------------------------------------------
- at INCLUDE:global-options@
+ at INCLUDE:global-options-formatter@
 .\" --- command specific options --- "/.
 .PP
 Command specific
 .IR options :
 .\"-------------------------------------
 .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 .
-.\"-------------------------------------
-.TP
 .BI \-x\  auth_info
 .I auth_info
 specifies additional conditions for the
-.B auth
-command.
+.BR "auth lookup" " and " "auth test"
+commands.
 The
 .I auth_info
 option string has to be given as
@@ -93,13 +78,103 @@
 .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
-.B doveadm auth \-x service=imap \-x rip=192.0.2.143 john johns_password
+.B doveadm auth test \-x service=imap \-x rip=192.0.2.143 john
+Password:
 passdb: john auth succeeded
 extra fields:
   user=john
@@ -109,4 +184,5 @@
 .\"------------------------------------------------------------------------
 .SH SEE ALSO
 .BR doveadm (1),
+.BR doveadm\-user (1),
 .BR doveconf (1)
\ No newline at end of file