Troubleshooting and Debugging

This page contains information on how to troubleshoot and debug issues that may occur with Dovecot Pro.

INFO

See Dovecot Pro SLA for information on how to contact Open-Xchange Support.

Crashes

Dovecot has been designed to crash rather than continue in a potentially unsafe manner that could cause data loss. Most crashes usually happen just once and retrying the operation will succeed, so usually even if you see them it's not a big problem.

Of course, all crashes are bugs that should eventually be fixed, so feel free to report them always even if they're not causing any visible problems.

Crashes appear in the logs like:

dovecot: Apr 23 11:16:05 Error: child 86116 (imap) killed with signal 11

Instead of crashing, there have been some rare bugs in Dovecot when some process could go into infinite loop, which causes the process to use 100% CPU.

If you detect such processes, it would be helpful to get a gdb backtrace of the running process:

gdb -p pid-of-process
bt full

After getting the backtrace, you can kill -9 the process.

dovecot-sysreport

TIP

This is the recommended way of providing debugging information as part of a Support ticket.

Use the dovecot-sysreport tool, which can be found in the Dovecot Pro packages:

dovecot-sysreport --core <binary> <core>

Session IDs

Each IMAP, POP3, and LMTP connection has its own unique session ID.

This ID is logged in all the lines and passed between Dovecot services, which allows tracking it all the way through proxies to backends and their various processes.

The session IDs look like <ggPiljkBBAAAAAAAAAAAAAAAAAAAAAAB>.

Manual Debugging

Process Tracing

If a Dovecot process hangs or is just really slow, the best way to debug it is to see what it's really doing.

TIP

If opening a support ticket with Dovecot, providing strace output (if available) can greatly improve resolution time.

Attach the output from the below command to the SLA ticket that is created.

# This should work on all Linux systems
# (strace must be available on the system - see your OS documentation for
# installation details)
strace -tt -o log -p <process pid>

Mail Debugging

Setting log_debug will make Dovecot log all kinds of things about mailbox initialization.

WARNING

This setting won't increase error logging at all, so if you're having some random problems it's unlikely to provide any help.

If there are any problems with a mailbox, Dovecot should automatically fix it. If that doesn't work for any reason, you can manually also request fixing a mailbox by running doveadm force-resync -u user@domain INBOX, where INBOX should be replaced with the folder that is having problems (or * if all folders should be fixed).

Users may sometimes complain that they have lost emails. The problem is almost always that this was done by one of the user's email clients accidentally. Especially accidentally configuring a "POP3 client" to a new device that deletes the mails after downloading them.

For this reason it's very useful to enable the mail-log plugin and enable logging for all the events that may cause mails to be lost. This way it's always possible to find out from the logs what exactly caused messages to be deleted.

If you're familiar enough with Dovecot's index files, you can use doveadm dump command to look at their contents in human readable format and possibly determine if there is something wrong in them.

Rawlogs

See rawlog.

Authentication Debugging

See Debugging Authentication.