File: //usr/share/man/man1/doveadm-auth.1
.TH "DOVEADM-AUTH" "1" "October 2025" "65dfbff" "Dovecot"
.SH "NAME"
\fBdoveadm-auth\fR - Flush/lookup/test authentication data
.SH "SYNOPSIS"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] \fBauth\fR \fIcommand\fR \[lB]\fIOPTIONS\fR\[rB] \[lB]\fIARGUMENTS\fR\[rB]
.SH "DESCRIPTION"
.P
The \fBdoveadm auth\fR \fICOMMANDS\fR can be used to perform various authentication related actions.
.SH "GLOBAL OPTIONS"
.P
Global doveadm(1)
.P
\fB-D\fR
.RS 0
.RS 4
.P
Enables \fIverbosity\fR and debug messages.
.RE 0
.RE 0
.P
\fB-O\fR
.RS 0
.RS 4
.P
Do not read any config file, just use defaults. The \fBdovecot_storage_version\fR setting defaults to the latest version, but can be overridden with
.RE 0
.RE 0
.P
\fB-k\fR
.RS 0
.RS 4
.P
Preserve entire environment for doveadm, not just \fBimport_environment\fR setting.
.RE 0
.RE 0
.P
\fB-v\fR
.RS 0
.RS 4
.P
Enables verbosity, including progress counter.
.RE 0
.RE 0
.P
\fB-i\fR \fIinstance-name\fR
.RS 0
.RS 4
.P
If using multiple Dovecot instances, choose the config file based on this instance name.
.P
See \fBinstance_name\fR setting for more information.
.RE 0
.RE 0
.P
\fB-c\fR \fIconfig-file\fR
.RS 0
.RS 4
.P
Read configuration from the given \fIconfig-file\fR. By default it first reads config socket, and then falls back to \fI/etc/dovecot/dovecot.conf\fR. You can also point this to config socket of some instance running compatible version.
.RE 0
.RE 0
.P
\fB-o\fR \fIsetting\fR\fB=\fR\fIvalue\fR
.RS 0
.RS 4
.P
Overrides the configuration \fIsetting\fR from \fI/etc/dovecot/dovecot.conf\fR and from the userdb with the given \fIvalue\fR. In order to override multiple settings, the \fB-o\fR option may be specified multiple times.
.RE 0
.RE 0
.P
\fB-f\fR \fIformatter\fR
.RS 0
.RS 4
.P
Specifies the \fIformatter\fR for formatting the output. Supported formatters are:
.P
\fBflow\fR
.RS 4
.P
prints each line with \fIkey\fR\fB=\fR\fIvalue\fR pairs.
.RE 0
.P
\fBjson\fR
.RS 4
.P
prints a JSON array of JSON objects.
.RE 0
.P
\fBpager\fR
.RS 4
.P
prints each \fIkey\fR: \fIvalue\fR pair on its own line and separates records with form feed character (\fB^L\fR).
.RE 0
.P
\fBtab\fR
.RS 4
.P
prints a table header followed by tab separated value lines.
.RE 0
.P
\fBtable\fR
.RS 4
.P
prints a table header followed by adjusted value lines.
.RE 0
.RE 0
.RE 0
.SH "OPTIONS"
.P
\fB-x\fR \fIauth_info\fR
.RS 0
.RS 4
.P
\fIauth_info\fR specifies additional conditions for the \fBuser\fR command. The \fIauth_info\fR option string has to be given as \fIname\fR \fB=\fR \fIvalue\fR pair. For multiple conditions the \fB-x\fR option could be supplied multiple times.
.P
Possible names for the \fIauth_info\fR are:
.P
\fBservice\fR
.RS 4
.P
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: \fBimap\fR, \fBpop3\fR or \fBsmtp\fR.
.RE 0
.P
\fBsession\fR
.RS 4
.P
Session identifier.
.RE 0
.P
\fBlip\fR
.RS 4
.P
The local IP address (server) for the test.
.RE 0
.P
\fBrip\fR
.RS 4
.P
The remote IP address (client) for the test.
.RE 0
.P
\fBlport\fR
.RS 4
.P
The local port, e.g. 143
.RE 0
.P
\fBrport\fR
.RS 4
.P
The remote port, e.g. 24567
.RE 0
.P
\fBreal_lip\fR
.RS 4
.P
The local IP to which the client connected on this host.
.RE 0
.P
\fBreal_rip\fR
.RS 4
.P
The remote IP where client connected from to this host.
.RE 0
.P
\fBreal_lport\fR
.RS 4
.P
The local port to which client connected to to this host.
.RE 0
.P
\fBreal_rport\fR
.RS 4
.P
The remote port from where the client connected from to this host.
.RE 0
.P
\fBforward_<field>\fR
.RS 4
.P
Field to forward as %{forward:field} to auth process.
.RE 0
.RE 0
.RE 0
.SH "ARGUMENTS"
.P
\fIuser\fR
.RS 0
.RS 4
.P
The \fIuser\fR's login name. Depending on the configuration, the login name may be for example \fBjane\fR or \fBjohn@example.com\fR.
.RE 0
.RE 0
.P
\fIpassword\fR
.RS 0
.RS 4
.P
Optionally the user's password. doveadm(1) will prompt for the password, if none was given.
.RE 0
.RE 0
.SH "COMMANDS"
.SS "auth cache flush"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] auth cache flush \[lB]\fB-a\fR \fImaster_socket_path\fR\[rB] \[lB]\fIuser\fR ...\[rB]
.P
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.
.P
\fB-a\fR \fImaster_socket_path\fR
.RS 0
.RS 4
.P
This option is used to specify an absolute path to an alternative UNIX domain socket.
.P
By default doveadm(1) will use the socket
.RE 0
.RE 0
.P
\fB-x\fR \fIauth_info\fR
.RS 0
.RS 4
.P
\fIauth_info\fR specifies additional conditions for the \fBuser\fR command. The \fIauth_info\fR option string has to be given as \fIname\fR \fB=\fR \fIvalue\fR pair. For multiple conditions the \fB-x\fR option could be supplied multiple times.
.P
Possible names for the \fIauth_info\fR are:
.P
\fBservice\fR
.RS 4
.P
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: \fBimap\fR, \fBpop3\fR or \fBsmtp\fR.
.RE 0
.P
\fBsession\fR
.RS 4
.P
Session identifier.
.RE 0
.P
\fBlip\fR
.RS 4
.P
The local IP address (server) for the test.
.RE 0
.P
\fBrip\fR
.RS 4
.P
The remote IP address (client) for the test.
.RE 0
.P
\fBlport\fR
.RS 4
.P
The local port, e.g. 143
.RE 0
.P
\fBrport\fR
.RS 4
.P
The remote port, e.g. 24567
.RE 0
.P
\fBreal_lip\fR
.RS 4
.P
The local IP to which the client connected on this host.
.RE 0
.P
\fBreal_rip\fR
.RS 4
.P
The remote IP where client connected from to this host.
.RE 0
.P
\fBreal_lport\fR
.RS 4
.P
The local port to which client connected to to this host.
.RE 0
.P
\fBreal_rport\fR
.RS 4
.P
The remote port from where the client connected from to this host.
.RE 0
.P
\fBforward_<field>\fR
.RS 4
.P
Field to forward as %{forward:field} to auth process.
.RE 0
.RE 0
.RE 0
.SS "auth lookup"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] auth lookup \[lB]\fB-a\fR \fIuserdb_socket_path\fR\[rB] \[lB]\fB-x\fR \fIauth_info\fR\[rB] \[lB]\fB-f\fR \fIfield\fR\[rB] \fIuser\fR \[lB]...\[rB]
.P
Similar to doveadm-user(1) command, except it performs a
.P
\fB-a\fR \fIuserdb_socket_path\fR
.RS 0
.RS 4
.P
This option is used to specify an absolute path to an alternative UNIX domain socket.
.P
By default doveadm(1) will use the socket
.RE 0
.RE 0
.P
\fB-f\fR \fIfield\fR
.RS 0
.RS 4
.P
When this option and the name of a userdb field is given, doveadm(1) will show only the value of the specified field.
.RE 0
.RE 0
.P
\fB-x\fR \fIauth_info\fR
.RS 0
.RS 4
.P
\fIauth_info\fR specifies additional conditions for the \fBuser\fR command. The \fIauth_info\fR option string has to be given as \fIname\fR \fB=\fR \fIvalue\fR pair. For multiple conditions the \fB-x\fR option could be supplied multiple times.
.P
Possible names for the \fIauth_info\fR are:
.P
\fBservice\fR
.RS 4
.P
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: \fBimap\fR, \fBpop3\fR or \fBsmtp\fR.
.RE 0
.P
\fBsession\fR
.RS 4
.P
Session identifier.
.RE 0
.P
\fBlip\fR
.RS 4
.P
The local IP address (server) for the test.
.RE 0
.P
\fBrip\fR
.RS 4
.P
The remote IP address (client) for the test.
.RE 0
.P
\fBlport\fR
.RS 4
.P
The local port, e.g. 143
.RE 0
.P
\fBrport\fR
.RS 4
.P
The remote port, e.g. 24567
.RE 0
.P
\fBreal_lip\fR
.RS 4
.P
The local IP to which the client connected on this host.
.RE 0
.P
\fBreal_rip\fR
.RS 4
.P
The remote IP where client connected from to this host.
.RE 0
.P
\fBreal_lport\fR
.RS 4
.P
The local port to which client connected to to this host.
.RE 0
.P
\fBreal_rport\fR
.RS 4
.P
The remote port from where the client connected from to this host.
.RE 0
.P
\fBforward_<field>\fR
.RS 4
.P
Field to forward as %{forward:field} to auth process.
.RE 0
.RE 0
.RE 0
.SS "auth test"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] auth test \[lB]\fB-a\fR \fIauth_socket_path\fR\[rB] \[lB]\fB-A\fR \fIsasl_mech\fR\[rB] \[lB]\fB-x\fR \fIauth_info\fR\[rB] \fIuser\fR \[lB]\fIpassword\fR\[rB]
.P
Test authentication for the given user.
.P
\fB-a\fR \fIauth_socket_path\fR
.RS 0
.RS 4
.P
This option is used to specify an absolute path to an alternative UNIX domain socket.
.P
By default doveadm(1) will use the socket
.RE 0
.RE 0
.P
\fB-A\fR \fIsasl_mech\fR
.RS 0
.RS 4
.P
The SASL mechanism used for the authentication. By default PLAIN is used.
.RE 0
.RE 0
.P
\fB-x\fR \fIauth_info\fR
.RS 0
.RS 4
.P
\fIauth_info\fR specifies additional conditions for the \fBuser\fR command. The \fIauth_info\fR option string has to be given as \fIname\fR \fB=\fR \fIvalue\fR pair. For multiple conditions the \fB-x\fR option could be supplied multiple times.
.P
Possible names for the \fIauth_info\fR are:
.P
\fBservice\fR
.RS 4
.P
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: \fBimap\fR, \fBpop3\fR or \fBsmtp\fR.
.RE 0
.P
\fBsession\fR
.RS 4
.P
Session identifier.
.RE 0
.P
\fBlip\fR
.RS 4
.P
The local IP address (server) for the test.
.RE 0
.P
\fBrip\fR
.RS 4
.P
The remote IP address (client) for the test.
.RE 0
.P
\fBlport\fR
.RS 4
.P
The local port, e.g. 143
.RE 0
.P
\fBrport\fR
.RS 4
.P
The remote port, e.g. 24567
.RE 0
.P
\fBreal_lip\fR
.RS 4
.P
The local IP to which the client connected on this host.
.RE 0
.P
\fBreal_rip\fR
.RS 4
.P
The remote IP where client connected from to this host.
.RE 0
.P
\fBreal_lport\fR
.RS 4
.P
The local port to which client connected to to this host.
.RE 0
.P
\fBreal_rport\fR
.RS 4
.P
The remote port from where the client connected from to this host.
.RE 0
.P
\fBforward_<field>\fR
.RS 4
.P
Field to forward as %{forward:field} to auth process.
.RE 0
.RE 0
.RE 0
.SS "auth login"
.P
\fBdoveadm\fR \[lB]\fIGLOBAL OPTIONS\fR\[rB] auth login \[lB]\fB-a\fR \fIauth_socket_path\fR\[rB] \[lB]\fB-m\fR \fIauth_master_socket_path\fR\[rB] \[lB]\fB-A\fR \fIsasl_mech\fR\[rB] \[lB]\fB-x\fR \fIauth_info\fR\[rB] \fIuser\fR \[lB]\fIpassword\fR\[rB]
.P
Test full login for the given user; i.e. performing both passdb lookup (authentication) and userdb lookup (login).
.P
\fB-a\fR \fIauth_socket_path\fR
.RS 0
.RS 4
.P
This option is used to specify an absolute path to an alternative UNIX domain socket.
.P
By default doveadm(1) will use the socket
.RE 0
.RE 0
.P
\fB-m\fR \fIauth_master_socket_path\fR
.RS 0
.RS 4
.P
This option is used to specify an absolute path to an alternative UNIX domain socket for the master socket.
.P
By default doveadm(1) will use the socket
.RE 0
.RE 0
.P
\fB-A\fR \fIsasl_mech\fR
.RS 0
.RS 4
.P
The SASL mechanism used for the authentication. By default PLAIN is used.
.RE 0
.RE 0
.P
\fB-x\fR \fIauth_info\fR
.RS 0
.RS 4
.P
\fIauth_info\fR specifies additional conditions for the \fBuser\fR command. The \fIauth_info\fR option string has to be given as \fIname\fR \fB=\fR \fIvalue\fR pair. For multiple conditions the \fB-x\fR option could be supplied multiple times.
.P
Possible names for the \fIauth_info\fR are:
.P
\fBservice\fR
.RS 4
.P
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: \fBimap\fR, \fBpop3\fR or \fBsmtp\fR.
.RE 0
.P
\fBsession\fR
.RS 4
.P
Session identifier.
.RE 0
.P
\fBlip\fR
.RS 4
.P
The local IP address (server) for the test.
.RE 0
.P
\fBrip\fR
.RS 4
.P
The remote IP address (client) for the test.
.RE 0
.P
\fBlport\fR
.RS 4
.P
The local port, e.g. 143
.RE 0
.P
\fBrport\fR
.RS 4
.P
The remote port, e.g. 24567
.RE 0
.P
\fBreal_lip\fR
.RS 4
.P
The local IP to which the client connected on this host.
.RE 0
.P
\fBreal_rip\fR
.RS 4
.P
The remote IP where client connected from to this host.
.RE 0
.P
\fBreal_lport\fR
.RS 4
.P
The local port to which client connected to to this host.
.RE 0
.P
\fBreal_rport\fR
.RS 4
.P
The remote port from where the client connected from to this host.
.RE 0
.P
\fBforward_<field>\fR
.RS 4
.P
Field to forward as %{forward:field} to auth process.
.RE 0
.RE 0
.RE 0
.SH "EXAMPLE"
.P
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.
.P
.RS 2
.nf
doveadm auth test -x service=imap -x rip=192.0.2.143 john
.fi
.RE
.P
.RS 2
.nf
Password:
passdb: john auth succeeded
extra fields:
user=john
.fi
.RE
.SH "REPORTING BUGS"
.P
Report bugs, including \fIdoveconf -n\fR output, to the Dovecot Mailing List \fI\(ladovecot@dovecot.org\(ra\fR. Information about reporting bugs is available at: https://dovecot.org/bugreport.html
.SH "SEE ALSO"
.P
doveadm(1)