Dovecot

Bugreport Mail

Please send bug reports to Dovecot mailing list. If it's not an entirely obvious bug, people in the list might be able to help figure it out. Also the bug report won't get accidentally lost in my INBOX then. Security related bugs should be sent directly to tss@iki.fi however.

You should mention in your bug report:

Dovecot version
Operating system or Linux distribution name
CPU architecture (x86 or something else?)
Filesystem you used (especially if you use NFS or not)
Some kind of description of what you were doing and with what IMAP client.
If the problem can be reproduced, it helps a lot if you can tell how. If it happens only with a specific mail, add it as attachment if possible. You can hide all the actual mail data from mboxes using mbox-anonymize.
Dovecot configuration with dovecot -n (Don't send the whole dovecot.conf file, it's way too large especially if you don't remove the comments)

Debugging crashes

Whenever Dovecot crashes, you see something like this in log file:

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

No matter how that happened, it's a bug and will be fixed if you can provide enough information on how it happened. Best way is to get backtrace from gdb, but the problem is that Dovecot doesn't dump core files by default. You can solve this in a few ways:

Core Dumps

To get core dumps from crashes, there are a few things you must do:

Set mail_drop_priv_before_exec = yes in config file.
userdb must have returned a home directory where the user is allowed to write. If you have problems getting the core file, verify with mail_debug = yes that it uses the correct home directory.
Dovecot must have been started without core dump size limit being too low. Run ulimit -c unlimited before starting Dovecot.
Linux: Make sure /proc/sys/kernel/core_pattern contains a proper value. By giving an absolute path to it (e.g. /var/core/%p) the users don't need a home directory.
FreeBSD: You can enable kern.sugid_coredump sysctl to avoid setting mail_drop_priv_before_exec and also to make login processes core dump (as well as other setuid/setgid binaries, so may not be a good permanent change!). kern.corefile sysctl can be used to specify core dump path to avoid having to set home directory and to make core dumping work with chrooted processes.

After all this is done, after a crash the user's home directory should contain a file named core, or sometimes code.pid where pid is a changing number.

Getting backtrace from core dump goes like:

gdb /usr/local/libexec/dovecot/imap /path/to/core
..
(gdb) bt full
#0  0x40048a51 in kill () from /lib/libc.so.6
#1  0x40048872 in raise () from /lib/libc.so.6
#2  0x40049986 in abort () from /lib/libc.so.6
... etc ...

Note that the core file must have been produced by the exact same binary you're giving to gdb, otherwise the backtrace is broken.

Talk IMAP Directly

You can run imap binary directly and talk IMAP protocol to it. For example:

MAIL=mbox:~/mail gdb /usr/local/libexec/dovecot/imap
...
(gdb) r
Starting program: /usr/local/libexec/dovecot/imap 
* PREAUTH [CAPABILITY IMAP4rev1 SORT THREAD=REFERENCES MULTIAPPEND UNSELECT
LITERAL+ IDLE CHILDREN LISTEXT LIST-SUBSCRIBED] Logged in as user

Then start typing IMAP commands, eg: x select inbox, x fetch 1:* (flags envelope bodystructure), x fetch 1 body.peek[]. When it crashes, execute bt full command in gdb.

Example Mail

Version: 1.0.beta2
OS: Debian unstable/x86

Program received signal SIGSEGV, Segmentation fault.
cmd_select (client=0x808d800) at cmd-select.c:87
87              char *x = 0; *x = 1;
(gdb) bt full
#0  cmd_select (client=0x808d800) at cmd-select.c:87
#1  0x0804d36a in client_handle_input (client=0x808d800) at client.c:306
#2  0x0804d439 in _client_input (context=0x808d800) at client.c:342
#3  0x08079038 in io_loop_handler_run (ioloop=0x808d0a8) at ioloop-poll.c:212
#4  0x08078b45 in io_loop_run (ioloop=0x808d0a8) at ioloop.c:295
#5  0x08052663 in main (argc=1, argv=0xbffff934, envp=0xbffff93c) at main.c:166

Debugging hangs

Check for a few seconds what system calls the process is doing. See ProcessTracing in Wiki for more information.

GDB backtrace can also be highly helpful, especially if process tracing doesn't show anything happening. Then it means Dovecot is in some infinite loop. You can get the backtrace by attaching GDB into the existing process:

gdb attach pid-of-hanging-process
..
(gdb) bt full
#0  cmd_select (client=0x808d800) at cmd-select.c:87
#1  0x0804d36a in client_handle_input (client=0x808d800) at client.c:306
#2  0x0804d439 in _client_input (context=0x808d800) at client.c:342
..
(gdb) quit

Client Traffic Sniffing

If a problem happens only with a specific client, the best way to figure out what's happening is to find out what it's actually talking to server. Some clients may provide logging on their own, or you can use some TCP traffic sniffer such as Wireshark or ngrep.

You can also use Dovecot's rawlog utility to log the traffic. It works also with SSL/TLS traffic.