Home / Alt manpages / doveadm-user(1)

  • doveadm-user(1)
  • User command
  • linux

Look Up Dovecot Userdb Records with doveadm user

A user cannot log in, and you need to know what Dovecot's userdb actually returns for them: doveadm user shows you. You will check the record for a login, select one returned field, and test lookup conditions such as the service or client address. The examples use Dovecot 2.3.21 from the installed dovecot-core package. Allow about ten minutes if Dovecot is already configured.

The route

Jump straight to the step you need, or tick off Done means at the end.

You need a shell and a configured Dovecot userdb. Most installations need elevated privileges because doveadm talks to Dovecot's authentication sockets.

Tip

The command only reads userdb data, but that data can contain account paths, IDs and other operational details. Treat its output as administrative information.

1. Check the command and configuration

Confirm which binary is being used and identify the installed package version:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

The manpage describes the Dovecot 2.3 interface. Later releases add or rename options, so use the local manual when you copy a command to another host:

$ doveadm help user | sed -n '1,35p'

Checkpoint

The synopsis should show doveadm [-Dv] user, followed by the -a, -f, -u and -x options. Do not use doveadm user --help, because this Dovecot 2.3 command does not define that long option.

2. Look up one login

Run a normal lookup with a real login name from your configuration. Replace the placeholder before running it:

$ sudo doveadm user [email protected]
userdb: [email protected]
  uid       : 8001
  gid       : 8001
  home      : /srv/mail/alice
  mail      : maildir:~/Maildir

The exact fields and values come from the userdb. A lookup can show uid, gid, home, mail, plugin settings and other fields. Do not treat the sample values as defaults for your server.

Some fields are filled from Dovecot configuration when the userdb does not return them. That is the default behaviour of doveadm user. It makes the ordinary lookup useful for the values Dovecot would use, but it can hide a missing field in the underlying userdb.

Checkpoint

Save the exit status immediately after the lookup if a script will act on it:

$ status=$?
$ printf 'doveadm status: %s\n' "$status"
doveadm status: 0

Do not infer success from a partial-looking line of output. Check the status, and investigate any non-zero result before changing userdb data or service configuration.

3. See only values the userdb returned

Use -u when you need to tell stored userdb fields apart from values supplied by Dovecot's configuration defaults:

$ sudo doveadm user -u [email protected]
userdb: [email protected]
  uid       : 8001
  gid       : 8001
  home      : /srv/mail/alice
  mail      : maildir:~/Maildir

Compare this with the ordinary lookup. If a field appears only without -u, configuration supplied it and the userdb did not return it. That distinction helps when you are debugging a SQL query, LDAP mapping or passwd-file record.

Tip

The -u option belongs to doveadm user here. It is not the same as the -u user-selection option used by several other doveadm commands.

4. Select one field

Use -f with a field name when a script or a quick check needs one value:

$ sudo doveadm user -f home [email protected]
field  value
home   /srv/mail/alice

The field name must be one that your userdb can return or that Dovecot can calculate for the lookup. Try a known field such as home, uid, gid or mail. An unknown or absent field is not evidence that the login does not exist.

Keep output handling conservative. Paths and account values may contain spaces or characters meaningful to a shell. If a script consumes the result, validate it for the specific field rather than evaluating the output as shell code.

5. Test conditions used by the userdb

Some SQL or passwd-file configurations use connection variables to choose a record or file. Supply those conditions with repeated -x options:

$ sudo doveadm user \
    -x service=imap \
    -x lip=192.0.2.10 \
    -x rip=198.51.100.25 \
    -x lport=143 \
    -x rport=49152 \
    [email protected]

The accepted names in this Dovecot 2.3 manpage are service, lip, rip, lport and rport. The addresses above are documentation ranges, not real client addresses. Use values matching the connection you want to test.

Multiple -x options express multiple conditions. Do not combine them into one comma-separated string.

This is a lookup test, not a login attempt. It does not authenticate the user, start an IMAP session or change the account. It does expose the result of a potentially conditional userdb query, so avoid pasting output into public tickets.

6. Handle wildcards and failures

The login argument accepts * and ? wildcards. Quote the argument so the shell does not expand the asterisk against filenames in the current directory:

$ sudo doveadm user -u '*[email protected]'
[email protected]
[email protected]

Use a wildcard only when listing matching accounts is acceptable. The output can disclose every matching login, and a broad pattern can produce more data than you expect.

If the command reports a socket or permission error, first check the service and socket configuration without editing it:

$ doveconf -n | sed -n '/^service auth {/,/^}/p'
$ ls -l /run/dovecot/auth-userdb

The default socket is /run/dovecot/auth-userdb. If Dovecot's base_dir was overridden, the socket can be elsewhere. The -a option selects an alternative absolute UNIX socket path:

$ sudo doveadm user -a /run/dovecot/auth-userdb -u [email protected]

Warning

Do not create a socket, loosen its permissions or restart Dovecot just because a lookup failed. First establish whether the failure is a wrong path, insufficient privilege, a stopped service or a userdb query problem.

Recovery

If you changed a temporary test configuration, restore the original file and reload only through your normal change process.

Done means

  • Versions known. You have the installed doveadm and dovecot-core versions.
  • Record checked. A real login returns the expected userdb record and a checked exit status.
  • Stored vs default. You used -u when stored fields had to be separated from configuration defaults, and -f for a specific field without executing its output as shell code.
  • Conditions documented. Conditional lookups use repeated -x name=value options.
  • Wildcards quoted. You used them only when the account disclosure was acceptable.
  • Nothing changed. No socket, permission, account or service state was altered while investigating.