Inspect Dovecot's Configuration Safely with doveconf

doveconf shows what Dovecot actually parsed, not what you think you wrote across a dozen included files. This guide covers dumping the effective configuration, querying individual settings, testing protocol or network-specific filters, and reviewing a change without exposing passwords or key contents. Allow about fifteen minutes; the examples use Dovecot 2.3.21+dfsg1-2ubuntu6.5 from the installed dovecot-core package on Ubuntu 24.04.5 LTS.

• A shell and a readable Dovecot configuration. This is a read-only inspection workflow throughout.
• sudo only where permissions actually block a read. It is not a default prefix for every command here.

1. Confirm the binary and its configuration source

Start by checking which executable your shell will run. This ordinary command needs no elevated privileges:

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

Unless you pass -c, the installed 2.3 manpage says doveconf reads /etc/dovecot/dovecot.conf. That file commonly includes drop-ins from conf.d, so inspecting one fragment alone can give a misleading answer; the command parses everything included and prints the effective result.

$ doveconf -n
# 2.3.21 (47349e2482): /etc/dovecot/dovecot.conf
# Pigeonhole version 0.5.21 (f6cd4b8e)
# OS: Linux 6.8.0-139-generic x86_64 Ubuntu 24.04.5 LTS
auth_mechanisms = plain login
mail_location = maildir:~/Maildir
protocols = imap pop3
ssl = required
...

Your host will have different settings. The useful checks are the version comment, the configuration path, and the settings you meant to change; if parsing fails, fix the reported syntax or include problem before touching service state.

2. Query one setting instead of dumping everything

Pass a setting name when you need a focused answer. The normal form includes the name:

$ doveconf service/imap/executable
service/imap/executable = imap

A slash addresses a setting inside a section. You can also request a whole section, such as service/imap, or several setting names in one invocation, which is easier to review than a large dump when you are checking one deployment assumption.

Use -h when another command needs only the value:

$ doveconf -h mail_plugins

On the inspected machine the value is empty, so the command prints a blank line. The option does not hide sensitive data; it only removes the setting name, so keep the labelled form for logs and human review unless a script genuinely needs the bare value.

To distinguish a configured value from Dovecot's default, add -d:

$ doveconf -d mail_plugins
mail_plugins =

Compare that output with doveconf mail_plugins: if the two differ, the effective configuration has overridden the default. An explicitly set value that happens to equal the default is visible with -N, while -n limits output to non-default values.

3. Inspect the result for a particular connection

Dovecot can select different settings by local name, local or remote address, protocol and service. Repeat -f for each condition, using the name=value form the installed manpage requires:

$ doveconf -f local=10.0.0.110 -f remote=10.11.1.2 -f service=pop3 -n
protocols = imap pop3
service pop3 {
  ...
}
...

Use values that match the conditions in your own configuration: local is the server address or hostname, while lname matches a local_name block, and protocol and service are different filters that should not be substituted for one another. For a smaller result, combine the filter with a setting name:

$ doveconf -h -f protocol=imap login_greeting
Dovecot ready.

The exact greeting is host-specific. The point of this check is that the filtered value is the one Dovecot would select for that protocol, not merely the global value.

4. Review a planned configuration change safely

When converting an old configuration or reviewing a proposed file, write output to a new path rather than overwriting the active file. This example reads an alternate configuration and creates a candidate:

$ doveconf -n -c /path/to/old-dovecot.conf > /path/to/dovecot.conf.new
$ test -s /path/to/dovecot.conf.new && echo 'candidate written'
candidate written

The redirection creates or truncates dovecot.conf.new, so choose a new filename; it does not alter the file named by -c. Review the candidate before installing it, and keep the current configuration available for recovery.

On a system using the usual include layout, configuration files are commonly edited under /etc/dovecot and /etc/dovecot/conf.d. Later settings can override earlier ones, so validate the merged result rather than trusting the filename you edited.

5. Keep secrets and file contents out of routine output

Routine -n output hides sensitive values. The installed manpage provides two switches that deliberately weaken that protection:

• -P shows passwords and other sensitive values.
• -x expands variables and reads file contents referenced by settings such as a certificate or key.

Do not add either option to a bug report, shell history shortcut or monitoring command by habit. A normal doveconf -n dump can still reveal usernames, mailbox paths, service topology and certificate filenames, so treat it as operational information: redact output before sharing it, and check the destination of any pipeline or redirect. -s shows hidden settings; the manpage warns that hidden settings should not normally be changed, and seeing a setting with -s is not a reason to edit it.

Common traps

• Output does not match the file you edited. Confirm the active path from the header of doveconf -n first, then inspect includes and repeat the query against the merged configuration; pass -c explicitly if you need another file, and keep its path visible in your notes.
• A setting is missing. Check its spelling and section path: doveconf mail_plugins asks for the global setting, while doveconf service/imap/executable addresses a nested one. A blank value can be valid, as the installed host's empty mail_plugins result demonstrates.
• A filtered query selects the wrong block. Verify the filter names and values, test one filter at a time, then combine them; a hostname pattern in a local_name block is not the same as a server address supplied through local.
• Permissions block reading an alternate file. Inspect its ownership and mode first, and only then consider a read-only privileged invocation such as sudo doveconf -n -c /path/to/dovecot.conf. Do not use sudo to conceal a syntax error, and do not pipe privileged output into an unreviewed file or remote command.