 1. Dovecot Logging
     1. Internal Errors
     2. Changing Log File Paths
     3. Rotating Logs
     4. Logging verbosity

Dovecot Logging
===============

*Dovecot always logs a detailed error message* if something goes wrong. If it
doesn't, it's considered a bug and will be fixed. However almost always the
problem is that you're looking at the wrong log file; error messages may be
logged to a different file than informational messages. By default Dovecot logs
to syslog using *mail* facility. You can change the facility from
'syslog_facility' setting. You can also configure Dovecot to write to log files
directly, see below.

When using syslog, Dovecot uses 4 different logging levels:

 * *info*: Informational and debug messages.
 * *warning*: Warnings that don't cause an actual error, but are useful to know
   about.
 * *err*: Non-fatal errors.
 * *crit*: Fatal errors that cause the process to die.

Where exactly these messages are logged depends entirely on your syslog
configuration. Often everything is logged to '/var/log/mail.log' or
'/var/log/maillog', and *err* and *crit* are logged to '/var/log/mail.err'.
This is not necessarily true for your configuration though.

You can find the correct log files using these methods:

 * Info log: After starting Dovecot, 'grep "starting up" /var/log/*'. It should
   show a line such as:'Dovecot v1.0.0 starting up'
 * Error logs: Use 'dovecot --log-error' command, which makes Dovecot log a few
   messages and exit. Then 'grep "This is Dovecot's" /var/log/*' to find them.
   You should see:
    * With Dovecot v1.0.0 you'll find only the *crit* log: 'This is Dovecot's
      error log'
    * With Dovecot v1.0.1+ you'll find all of them:
       * *warning*: 'This is Dovecot's warning log'
       * *err*: 'This is Dovecot's error log'
       * *crit*: 'This is Dovecot's fatal log'
 * You can also check your '/etc/syslog.conf' to see how it's configured.

Internal Errors
---------------

If IMAP or POP3 processes encounter some error, they don't show the exact
reason for clients. Instead they show:

---%<-------------------------------------------------------------------------
Internal error occurred. Refer to server log for more information. [2006-01-07
22:35:11]
---%<-------------------------------------------------------------------------

The point is that whenever anything unexpected happens, Dovecot doesn't leak
any extra information about it to clients. They don't need it and they might
try to exploit it in some ways, so the less they know the better.

The real error message is written to the error log file. The timestamp is meant
for you to help you find it.

Changing Log File Paths
-----------------------

If you don't want to use syslog, or if you just can't find the Dovecot's error
logs, you can make Dovecot log elsewhere as well:

---%<-------------------------------------------------------------------------
log_path = /var/log/dovecot.log
# If you want everything in one file, just don't specify info_log_path
info_log_path = /var/log/dovecot-info.log
---%<-------------------------------------------------------------------------

The warning and error messages will go to file specified by 'log_path', while
everything else goes to 'info_log_path'. If you do this, make sure you're
really looking at the 'log_path' file for error messages, since the "Starting
up" message is written to 'info_log_path' file.

Rotating Logs
-------------

If you change from syslog to an external log file, you can use logrotate
(available on most recent linux distros) to maintain the Dovecot logfile so it
doesn't grow beyond a manageable size. Save the below scriptlet as
'/etc/logrotate.d/dovecot':

---%<-------------------------------------------------------------------------
# dovecot SIGUSR1: Re-opens the log files.
/var/log/dovecot*.log {
  missingok
  notifempty
  delaycompress
  sharedscripts
  postrotate
    /bin/kill -USR1 `cat /var/run/dovecot/master.pid 2>/dev/null` 2> /dev/null
|| true
  endscript
}
---%<-------------------------------------------------------------------------

*NOTE*: change the path to the logfile(s) and the 'master.pid' file as
appropriate for your system configuration. The default location of 'master.pid'
is '/usr/local/var/run/dovecot/master.pid'.

Logging verbosity
-----------------

There are several settings that control logging verbosity. By default they're
all disabled, but they may be useful for debugging.

 * 'auth_verbose=yes' enables logging all failed authentication attempts.
 * 'auth_debug=yes' enables all authentication debug logging (also enables
   'auth_verbose'). Passwords are logged as '<hidden>'.
 * 'auth_debug_passwords=yes' does everything that 'auth_debug=yes' does, but
   it also removes password hiding.
 * 'mail_debug=yes' enables all kinds of mail related debug logging, such as
   showing where Dovecot is looking for mails.
 * 'verbose_ssl=yes' enables logging SSL errors and warnings. Even without this
   setting if connection is closed because of an SSL error, the error is logged
   as the disconnection reason (v1.1+).

(This file was created from the wiki on 2009-02-04 04:42)
