DOVEADM-USER(1)

💖 doveadm-user 💖

okay bestie, sit down, hydrate, because we're about to do a user lookup and it's gonna be adorable. this is part of doveadm(1) — the Dovecot admin tool — and honestly? she's giving backstage-pass energy. she walks into Dovecot's userdbs and asks "hey, do you know this person, and what do you know about them?" 🎀

---

✨ NAME ✨

doveadm-user — perform a user lookup in Dovecot's userdbs 🦋

---

✨ SYNOPSIS ✨

doveadm [GLOBAL OPTIONS] user [-a userdb_socket_path] [-e template] [-f field] [-u] [-x auth_info] user...

---

✨ DESCRIPTION ✨

the user command does a user lookup — it shows you exactly what info Dovecot sees about the user(s), or whether the user even exists at all in the configured userdb(s). no cap. 🔍

the auth_info is lowkey the moment when the userdb is, like, a SQL database and you're using %variables in the userdb_sql_query setting — think %{protocol} or %{local_ip}. or when you've configured your userdb like this:

userdb passwd-file {
  passwd_file_path = /etc/%{protocol}.passwd
}

see how the path literally changes per protocol? yeah. that's why auth_info exists. she's the context. 💅

---

✨ GLOBAL OPTIONS ✨

the global doveadm(1) options, bestie:

• -D — enables verbosity and debug messages. she's chatty now 🗣️
• -O — do not read any config file, just use defaults. the dovecot_storage_version setting defaults to the latest version, but you can override it with -o. (yes, -O big letter, -o little letter, they are NOT the same girl 💀)
• -k — preserve the entire environment for doveadm, not just the import_environment setting.
• -v — enables verbosity, including a progress counter. little numbers go brrr ⭐
• -i instance-name — if you're running multiple Dovecot instances, pick the config file based on this instance name. see the instance_name setting for more info.
• -c config-file — read configuration from the given config-file. by default it first reads the config socket, then falls back to /etc/dovecot/dovecot.conf. you can also point this at the config socket of some instance running a compatible version. 🫶
• -o setting=value — overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. wanna override multiple settings? specify -o multiple times, she doesn't mind. 👑

---

✨ OPTIONS ✨

• -a userdb_socket_path — use this to specify an absolute path to an alternative UNIX domain socket. by default doveadm(1) uses the socket /rundir/auth-userdb. the socket might live in another directory when the default base_dir setting was overridden in /etc/dovecot/dovecot.conf.
• -e template — when you give this option plus a string with %variables, doveadm(1) shows you the expanded string for the user. ✨ this option can't be used together with the -e… wait no, with the -f or -u options. (pick a lane, queen)
• -f field — when you give this option plus the name of a userdb field, doveadm(1) shows only the value of that specified field. this option can't be used together with the -e or -u options.
• -u — when given, doveadm(1) shows only values from the userdb. without the -u parameter, if any of the uid, gid, home or mail_path fields are missing, their defaults are taken from the configuration file. this option can't be used together with the -e or -f 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 can 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.

---

✨ ARGUMENTS ✨

• user — a user's login name. depending on the configuration, a login name may be for example jane or ⟨john@example.com⟩. it's also possible to use '*' and '?' wildcards (e.g. -u \*@example.org). 🎀

---

✨ EXAMPLE ✨

perform a user lookup for the users jane and ⟨john@example.com⟩:

doveadm user jane john@example.com

userdb: jane
  uid       : 8001
  gid       : 8001
  home      : /home/jane
  mail_path : ~/sdbox
  plugins   : sieve
  quota_storage_size: 150M

userdb: john@example.com
  home      : /srv/mail/8/70312/79832
  uid       : 79832
  gid       : 70312
  mail_path : ~/mdbox

user lookup, using wildcards:

doveadm user \*.?oe@example.net

jane.doe@example.net
judy.roe@example.net
john.doe@example.net

look at her go. three whole users from one wildcard. she ate. 💅✨

---

✨ 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⟩

bestie please include that doveconf -n output. the maintainers are begging. it's the love language of bug reports. 🫶

---

✨ SEE ALSO ✨

• doveadm(1)

---

and that's the whole page, bestie 🦋 go forth and look up users, be iconic, and remember: wildcards are powerful and with great power comes great \* escaping. iykyk. 🌸

this was DOVEADM-USER(1) from the Dovecot manual, revision f979264, dated April 2026. mwah. 💖✨