Run Dovecot Helper Binaries with doveadm exec

You need to run a Dovecot helper such as dovecot-lda with the right configuration, and doveadm exec does it without guessing paths. Allow about ten minutes if you already know which helper you need.

You will finish with a reliable way to invoke an executable from Dovecot's libexec_dir, pass its arguments unchanged, and apply a temporary configuration override when needed. The examples match Dovecot 2.3.21 from the installed dovecot-core package, version 1:2.3.21+dfsg1-2ubuntu6.5.

1. Check the command and helper directory

Confirm that doveadm is installed and inspect the helper you intend to run. The installed manual describes the executable directory as /usr/lib/dovecot on this system.

$ command -v doveadm
/usr/bin/doveadm
$ ls -l /usr/lib/dovecot/dovecot-lda
-rwxr-xr-x 1 root root ... /usr/lib/dovecot/dovecot-lda

Replace dovecot-lda with the actual file name in that directory. Do not pass an arbitrary path as the binary argument, and do not assume a command found elsewhere in PATH is eligible. The name is resolved by Dovecot's configured libexec directory.

Checkpoint: If command -v doveadm fails, stop and install or repair the Dovecot package through your normal system-management process. If the helper is absent, check the package contents before changing configuration.

2. Start with a non-destructive binary check

Use a helper whose own arguments have a read-only effect, if your installation has one. doveadm exec has no special help mode of its own. Everything after the binary name is passed to that binary, so its accepted options decide what happens.

$ doveadm exec dovecot-lda --help
Error: net_connect_unix(/run/dovecot/stats-writer) failed: Permission denied
/usr/lib/dovecot/dovecot-lda: invalid option -- '-'
Usage: dovecot-lda [-c <config file>] [-d <username>] [-p <path>]
                   [-m <mailbox>] [-e] [-k] [-f <envelope sender>]
                   [-a <original envelope recipient>]
                   [-r <final envelope recipient>]

That probe shows argument pass-through, but it is not a successful LDA invocation: this installed helper does not document --help. The stats-writer warning is environment-specific and can appear before the helper's own output when the invoking account cannot reach Dovecot's socket. The final exit status is the part that matters:

$ doveadm exec dovecot-lda --help
$ printf 'exit=%s\n' "$?"
exit=64

Warning: Do not turn this test into a delivery test. A command that includes a destination user and message input can alter a mailbox.

3. Run a helper with its documented arguments

The manual's representative operation delivers a message through Dovecot LDA. It reads the message from standard input and takes the recipient and envelope sender as arguments:

$ doveadm exec dovecot-lda -d [email protected] \
    -f [email protected] < /path/to/welcome.msg

Warning: This is a state-changing operation. It may deliver to [email protected], invoke mailbox rules and create or update delivery state. Verify the recipient, sender, input file and Dovecot configuration first. Use a disposable test mailbox only when your mail setup provides one, and do not paste a real production address into a copied example unchecked.

Privileges depend on the helper, its configuration and the account running doveadm. Start as the least-privileged account that should perform the operation. Add sudo only when your local Dovecot administration policy requires it and you have checked the resulting user and configuration context:

$ sudo doveadm exec dovecot-lda -d [email protected] \
    -f [email protected] < /path/to/welcome.msg

Recovery: There is no general undo command for a message already delivered. If this was a test, remove the test message using your normal mailbox tooling after confirming its location. Keep the source message file until delivery has been verified.

4. Pass a temporary Dovecot setting

Global doveadm options come before exec. The -o option overrides a setting from /etc/dovecot/dovecot.conf and the user database for this invocation. Repeat it for multiple settings.

$ doveadm -o setting=value exec binary-name binary-argument
$ doveadm -o setting-one=value-one \
    -o setting-two=value-two \
    exec binary-name binary-argument

These are syntax templates, not runnable configuration values. Substitute settings the selected helper actually reads, and quote values containing spaces or shell metacharacters. A temporary override lasts only for this invocation and does not rewrite /etc/dovecot/dovecot.conf, but it can still change security or delivery behaviour while the helper runs.

Tip: Keep the boundary clear. doveadm -o ... exec applies global options, while options after the binary name belong to the helper. For example, -d belongs to dovecot-lda; it is not a doveadm option.

5. Use verbosity only while diagnosing

Add -v before exec for verbosity and a progress counter, or -D for debug messages:

$ doveadm -v exec binary-name binary-argument
$ doveadm -D exec binary-name binary-argument

Warning: Debug output can disclose paths, configuration details or identifiers. Capture it only where access is appropriate, and strip copied logs from shared tickets when they contain sensitive mailbox or host information.

Neither option makes a failed helper safe to ignore, and neither changes the helper's own argument rules.

6. Diagnose a failed invocation

First record the status immediately after the command:

doveadm exec binary-name binary-argument
status=$?
printf 'doveadm exec exit status: %s\n' "$status"
exit "$status"

Then match the symptom:

For an LDA operation, verify the input file without changing it:

$ test -r /path/to/welcome.msg && echo readable
$ wc -c /path/to/welcome.msg

Warning: Do not retry a delivery blindly after an ambiguous failure. Check the mailbox and Dovecot logs for a duplicate delivery first, then decide whether to retry. The command may have reached the helper even if doveadm also reported a local socket warning.

Done means