---
name: "doveadm-user"
section: "1"
platform: "linux"
package: "dovecot"
version: "2.4.5-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/doveadm-user"
---

# doveadm-user(1)

Perform a user lookup in Dovecot's userdbs

## 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 is used to perform a user lookup - to show what information Dovecot sees about the *user* (s), or if it exists at all in the configured *userdb* (s).

The *auth\_info* may be useful when the userdb is for example a SQL database and you are using %variables, like **%{protocol}** or **%{local\_ip}**, in the *userdb\_sql\_query* setting. Or when you have configured the userdb in a way like this:

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

## GLOBAL OPTIONS

Global [doveadm(1)](/doveadm/1.md) *options*:

- **-D**

  Enables *verbosity* and debug messages.

- **-O**

  Do not read any config file, just use defaults. The **dovecot\_storage\_version** setting defaults to the latest version, but can be overridden with **-o**.

- **-k**

  Preserve entire environment for doveadm, not just **import\_environment** setting.

- **-v**

  Enables verbosity, including progress counter.

- **-i** *instance-name*

  If using multiple Dovecot instances, choose the config file based on this instance name.

  See **instance\_name** setting for more information.

- **-c** *config-file*

  Read configuration from the given *config-file*. By default it first reads config socket, and then falls back to */etc/dovecot/dovecot.conf*. You can also point this to config socket of some instance running compatible version.

- **-o** *setting***=***value*

  Overrides the configuration *setting* from */etc/dovecot/dovecot.conf* and from the userdb with the given *value*. In order to override multiple settings, the **-o** option may be specified multiple times.

## OPTIONS

- **-a** *userdb\_socket\_path*

  This option is used to specify an absolute path to an alternative UNIX domain socket.

  By default [doveadm(1)](/doveadm/1.md) will use the socket */rundir/auth-userdb*. The socket may be located in another directory, when the default *base\_dir* setting was overridden in */etc/dovecot/dovecot.conf*.

- **-e** *template*

  When this option and a string with %variables is given, [doveadm(1)](/doveadm/1.md) will show the expanded string for the user. This option can't be used together with the **-f** or **-u** options.

- **-f** *field*

  When this option and the name of a userdb field is given, [doveadm(1)](/doveadm/1.md) will show only the value of the specified field. This option can't be used together with the **-e** or **-u** options.

- **-u**

  When this option is given, [doveadm(1)](/doveadm/1.md) will only show values from the *userdb*. Without **-u** parameter if any of the *uid*, *gid*, *home* or *mail\_path* fields are missing, their defaults are taken from 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 *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.

## ARGUMENTS

*user*

Is 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
```

## REPORTING BUGS

Report bugs, including *doveconf -n* output, to the Dovecot Mailing List *⟨dovecot@dovecot.org⟩*. Information about reporting bugs is available at: *⟨https://dovecot.org/bugreport.html⟩*

## SEE ALSO

[doveadm(1)](/doveadm/1.md)