When working with Dovecot 2.0.11 on FreeBSD systems, a common challenge emerges when handling email-format usernames (user@domain) while using the passwd driver for authentication. The system correctly authenticates local users (like 'webmaster') but fails when presented with full email addresses (like 'webmaster@domain.com').

With the default configuration:

userdb {
  driver = passwd
}

passdb {
  driver = passwd
}

Dovecot attempts exact matches against system usernames. Since Unix systems don't store email-format usernames in /etc/passwd, lookups naturally fail.

Many administrators try using the username_format parameter:

passdb {
  args = username_format=%n
  driver = passwd
}

userdb {
  args = username_format=%n
  driver = passwd
}

This leads to connection failures because:

1. The parameter name is incorrect (should be username_filter in older Dovecot versions)
2. The syntax isn't properly supported by the passwd driver

For proper functionality with both formats:

passdb {
  driver = passwd
  args = username_filter=%n
}

userdb {
  driver = passwd
  args = username_filter=%n
}

The %n variable extracts the local part before the @ symbol. For Dovecot 2.2.0+, use:

passdb {
  driver = passwd
  args = username_format=%n
}

userdb {
  driver = passwd
  args = username_format=%n
}

For more control, combine with the static driver:

userdb {
  driver = static
  args = uid=vmail gid=vmail home=/var/vmail/%d/%n
}

Enable detailed logging with:

auth_verbose = yes
auth_debug = yes
auth_debug_passwords = yes

• Verify your Dovecot version with dovecot --version
• Check /etc/login.conf for FreeBSD-specific user authentication settings
• Ensure proper permissions for mail directories

After changes, test with:

doveadm auth test webmaster@domain.com

And verify user lookup:

doveadm user webmaster@domain.com

Here's a complete working snippet for Dovecot 2.0.x:

auth_mechanisms = plain login
passdb {
  driver = passwd
  args = username_filter=%n
}
userdb {
  driver = passwd
  args = username_filter=%n
}

---

When using Dovecot with passwd driver for authentication, a common problem occurs where user lookups fail for email-style usernames (username@domain) while working fine for system usernames. The debug logs show:

auth: passwd(webmaster@myregisteredname.com): unknown user
auth: Debug: passwd(webmaster@myregisteredname.com): lookup
auth: Debug: master out: NOTFOUND  1

The passwd driver by default expects system usernames without domain parts. When an email format arrives, Dovecot tries to lookup the complete string "webmaster@myregisteredname.com" in /etc/passwd, which obviously fails.

We need to configure Dovecot to strip the domain portion before passwd lookup. The correct configuration in dovecot.conf should be:

passdb {
  driver = passwd
  args = username_format=%n
}
userdb {
  driver = passwd
  args = username_format=%n
}

The %n format specifier extracts just the username portion before the @ symbol.

1. For Dovecot 2.2.x and later, use this syntax:

passdb {
  driver = passwd
  args = username_filter=%n
}

2. If you're using PAM authentication instead of pure passwd:

passdb {
  driver = pam
  args = username_format=%n
}

If you encounter errors like:

doveadm(root): Error: userdb lookup(webmaster@myregisteredname.com): Disconnected unexpectedly

Check these aspects:

1. Verify Dovecot version compatibility
2. Ensure no syntax errors in the configuration
3. Check auth debug logs for specific error messages

For more complex setups, consider:

1. Using virtual users with passwd-file
2. Implementing LDAP authentication
3. Creating a custom userdb module

Here's a sample virtual users configuration:

passdb {
  driver = passwd-file
  args = username_format=%n /etc/dovecot/users
}
userdb {
  driver = passwd-file
  args = username_format=%n /etc/dovecot/users
}

After configuration changes, always test with:

doveadm reload
doveadm user webmaster@domain.com
doveadm user webmaster

Both commands should return valid user information if configured correctly.