DOVEADM-AUTH(1)

💖 DOVEADM-AUTH 💖

okay bestie, welcome to doveadm-auth from the Dovecot manual, section 1 🫶 this is the part of doveadm(1) that handles ✨authentication✨ stuff — flushing it, looking it up, testing it. iconic behaviour honestly.

---

🌸 NAME 🌸

doveadm-auth — flush/lookup/test authentication data 💅

---

🎀 SYNOPSIS 🎀

doveadm [GLOBAL OPTIONS] auth command [OPTIONS] [ARGUMENTS]

like. that's the whole shape of it. you got your global options, you say auth, you pick a command, and then the command gets its own options and arguments. slay.

---

🦋 DESCRIPTION 🦋

the doveadm auth COMMANDS are literally here so you can do all kinds of authentication-related actions. that's it. that's the vibe. no cap.

---

✨ GLOBAL OPTIONS ✨

these are the global doveadm(1) options, so they apply across the board, not just to auth:

• -D — turns on verbosity and debug messages. messy but informative, we love her.
• -O — do not read any config file at all, just use the defaults. heads up tho: the dovecot_storage_version setting defaults to the latest version, but you can override it with -o.
• -k — preserve the entire environment for doveadm, not just the import_environment setting. full send, no filter.
• -v — enables verbosity, including a progress counter. so you can watch the little numbers go up 😌
• -i instance-name — if you're running multiple Dovecot instances, this picks which config file to use based on the instance name. check the instance_name setting for the deets.
• -c config-file — read configuration from the given config-file. by default it reads the config socket first, and then falls back to /etc/dovecot/dovecot.conf. you can also point this at the config socket of some instance running a compatible version. versatile queen.
• -o setting=value — overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. wanna override multiple settings? just pass -o multiple times. periodt.
• -f formatter — specifies the formatter for formatting the output. the supported formatters are:
  • flow — prints each line with key=value pairs.
  • json — prints a JSON array of JSON objects.
  • pager — prints each key: value pair on its own line and separates records with the form feed character (^L).
  • tab — prints a table header followed by tab separated value lines.
  • table — prints a table header followed by adjusted value lines.

---

💅 OPTIONS 💅

• -x auth_info — auth_info specifies additional conditions for the user command. the auth_info option string has to be given as a name = value pair. for multiple conditions, the -x option could be supplied multiple times. stack 'em.

the possible names for the auth_info are:

• service — 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: imap, pop3 or smtp.
• session — session identifier.
• lip — the local IP address (server) for the test.
• rip — the remote IP address (client) for the test.
• lport — the local port, e.g. 143
• rport — the remote port, e.g. 24567
• real_lip — the local IP to which the client connected on this host.
• real_rip — the remote IP where client connected from to this host.
• real_lport — the local port to which client connected to to this host.
• real_rport — the remote port from where the client connected from to this host.
• forward_<field> — field to forward as %{forward:field} to auth process.

---

🌈 ARGUMENTS 🌈

• user — the user's login name. depending on the configuration, the login name may be for example jane or john@example.com. iykyk.
• password — optionally the user's password. doveadm(1) will prompt for the password, if none was given. so don't stress, she'll ask 🫶

---

💅 COMMANDS 💅

🧼 auth cache flush

doveadm [GLOBAL OPTIONS] auth cache flush [-a master_socket_path] [user-mask ...]

Bestie, this one flushes the authentication cache. By default the cache is flushed for all the users — which, fun fact, you can also pull off by sending SIGHUP to the auth process. And if you only wanna nuke one or a few users, just hand over a user-mask that matches their usernames. ✨

• -a master_socket_path — this option lets you point at an absolute path to an alternative UNIX domain socket. By default doveadm(1) will use the socket /rundir/auth-master. That socket might be living somewhere else entirely if the default base_dir setting got overridden in /etc/dovecot/dovecot.conf. 🏠
• -x auth_info — auth_info is where you drop additional conditions for the user command. It has to be given as a name = value pair. Need more than one condition? Just supply the -x option multiple times, no big deal. 💁‍♀️

Possible names for the auth_info are:

• service — 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: imap, pop3 or smtp.
• session — session identifier.
• lip — the local IP address (server) for the test.
• rip — the remote IP address (client) for the test.
• lport — the local port, e.g. 143
• rport — the remote port, e.g. 24567
• real_lip — the local IP to which the client connected on this host.
• real_rip — the remote IP where client connected from to this host.
• real_lport — the local port to which client connected to to this host.
• real_rport — the remote port from where the client connected from to this host.
• forward_<field> — field to forward as %{forward:field} to auth process.

---

🔍 auth lookup

doveadm [GLOBAL OPTIONS] auth lookup [-a userdb_socket_path] [-x auth_info] [-f field] user [...]

Super similar to the doveadm-user(1) command, except it performs a passdb lookup (without authentication) instead of a userdb lookup. Sneaky little switch-up, honestly iconic. 😌

• -a userdb_socket_path — this option specifies an absolute path to an alternative UNIX domain socket. By default doveadm(1) will use the socket /rundir/auth-userdb. That socket may sit in another directory when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf. 🌸
• -f field — when this option and the name of a userdb field are given, doveadm(1) will show only the value of the specified field. Just the value, nothing else, periodt. 🎯
• -x auth_info — auth_info specifies additional conditions for the user command. The auth_info option string has to be given as a name = value pair. For multiple conditions the -x option could be supplied multiple times. 💫

Possible names for the auth_info are:

• service — 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: imap, pop3 or smtp.
• session — session identifier.
• lip — the local IP address (server) for the test.
• rip — the remote IP address (client) for the test.
• lport — the local port, e.g. 143
• rport — the remote port, e.g. 24567
• real_lip — the local IP to which the client connected on this host.
• real_rip — the remote IP where client connected from to this host.
• real_lport — the local port to which client connected to to this host.
• real_rport — the remote port from where the client connected from to this host.
• forward_<field> — field to forward as %{forward:field} to auth process.

---

🧪 auth test

doveadm [GLOBAL OPTIONS] auth test [-a auth_socket_path] [-A sasl_mech] [-x auth_info] user [password]

Tests authentication for the given user. Vibe check on the credentials, basically. 🔐

• -a auth_socket_path — this option specifies an absolute path to an alternative UNIX domain socket. By default doveadm(1) will use the socket /rundir/auth-client. The socket may be located in another directory when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf. 🏡
• -A sasl_mech — the SASL mechanism used for the authentication. By default PLAIN is used. No cap. 💅
• -x auth_info — auth_info specifies additional conditions for the user command. The auth_info option string has to be given as a name = value pair. For multiple conditions the -x option could be supplied multiple times. 🫶

Possible names for the auth_info are:

• service — 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: imap, pop3 or smtp.
• session — session identifier.
• lip — the local IP address (server) for the test.
• rip — the remote IP address (client) for the test.
• lport — the local port, e.g. 143
• rport — the remote port, e.g. 24567
• real_lip — the local IP to which the client connected on this host.
• real_rip — the remote IP where client connected from to this host.
• real_lport — the local port to which client connected to to this host.
• real_rport — the remote port from where the client connected from to this host.
• forward_<field> — field to forward as %{forward:field} to auth process.

---

🚪 auth login

doveadm [GLOBAL OPTIONS] auth login [-a auth_socket_path] [-m auth_master_socket_path] [-A sasl_mech] [-x auth_info] user [password]

Tests a full login for the given user — meaning it does both the passdb lookup (authentication) and the userdb lookup (login). The whole glow-up, start to finish. 👑

• -a auth_socket_path — this option specifies an absolute path to an alternative UNIX domain socket. By default doveadm(1) will use the socket /rundir/auth-client. The socket may be located in another directory when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf. 🌷
• -m auth_master_socket_path — this option specifies an absolute path to an alternative UNIX domain socket for the master socket. By default doveadm(1) will use the socket /rundir/auth-master. The socket may be located in another directory when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf. 🗝️
• -A sasl_mech — the SASL mechanism used for the authentication. By default PLAIN is used. ⭐
• -x auth_info — auth_info specifies additional conditions for the user command. The auth_info option string has to be given as a name = value pair. For multiple conditions the -x option could be supplied multiple times. 💜

Possible names for the auth_info are:

• service — 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: imap, pop3 or smtp.
• session — session identifier.
• lip — the local IP address (server) for the test.
• rip — the remote IP address (client) for the test.
• lport — the local port, e.g. 143
• rport — the remote port, e.g. 24567
• real_lip — the local IP to which the client connected on this host.
• real_rip — the remote IP where client connected from to this host.
• real_lport — the local port to which client connected to to this host.
• real_rport — the remote port from where the client connected from to this host.
• forward_<field> — field to forward as %{forward:field} to auth process.

---

🍓 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.

doveadm auth test -x service=imap -x rip=192.0.2.143 john

Password:
passdb: john auth succeeded
extra fields:
  user=john

She ate and left no crumbs. 💖

---

🐛 REPORTING BUGS 🐛

Found a bug? 😭 Report bugs, including doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. Info about reporting bugs lives at: ⟨https://dovecot.org/bugreport.html⟩

Don't forget the doveconf -n output bestie, they need the receipts. 🧾

---

👀 SEE ALSO 👀

• doveadm(1)

---

That's the whole page, babe — brought to you from source version f979264, dated April 2026. Go forth and authenticate responsibly. 💅✨🎀