 1. Upgrading Dovecot from v1.0.x to v1.0.y
 2. Upgrading Dovecot from v0.99.x to v1.0
     1. Configuration file
     2. PAM
     3. SQL Configuration
     4. Subscriptions
     5. Keywords
     6. POP3 UIDLs
     7. mbox errors
     8. Port Changes
     9. Log Changes for POP before SMTP

Upgrading Dovecot from v1.0.x to v1.0.y
=======================================

The NEWS file [http://dovecot.org/doc/NEWS] contains all the important changes
marked with "*" character. Read them to see if there is anything that concerns
you. In general all the changes try to preserve backwards compatibility, but
some changes which are meant to improve the stability and correctness of the
configuration could mean breaking some existing installations. And that may be
a good thing, since it can expose problems which could otherwise show up as
random errors.

Upgrading Dovecot from v0.99.x to v1.0
======================================

The upgrade from Dovecot v0.99.x to v1.0 isn't just a drop-in upgrade, but also
requires the administrator to adjust the configuration in several places, as
detailed in the chapters below.

Configuration file
------------------

The configuration file has had a lot of changes, so it's better to just modify
the included 'dovecot-example.conf' file manually. The easiest way to remember
what you had changed in the old file is with grep:

---%<-------------------------------------------------------------------------
egrep -v '^ *(#|$)'|less
---%<-------------------------------------------------------------------------

PAM
---

Dovecot v0.99.x defaulted to using "imap" or "pop3" PAM service identifiers,
ie.'/etc/pam.d/imap' or '/etc/pam.d/pop3' files. With v1.0, the default is to
use "dovecot" service identifier, i.e.'/etc/pam.d/dovecot'. Either change the
passdb pam args to use the "*" parameter or set up the '/etc/pam.d/' files
properly.

SQL Configuration
-----------------

The SQL configuration has changed. 'password_query' in the new dovecot-sql.conf
must return a field named 'password'.

Subscriptions
-------------

*Maildir only*: The filename that stores user subscriptions has changed from
'.subscriptions' to 'subscriptions'. (It is still called '.subscriptions' for
mbox.). Since v1.0.rc2 the renaming is done automatically.

Keywords
--------

*Maildir-only*: The former '.customflags' file has been renamed to
*dovecot-keywords*, which is incompatible with v0.99.x's format. Since v1.0.rc2
Dovecot can convert the file automatically.

POP3 UIDLs
----------

If your users keep their mails in the POP3 server and you don't want to cause
their mails to be downloaded again, you'll need to set:

---%<-------------------------------------------------------------------------
pop3_uidl_format = %v.%u
---%<-------------------------------------------------------------------------

However this doesn't work well for Outlook 2003 users (as it didn't with
v0.99.x either), which is the reason this isn't the default anymore.

mbox errors
-----------

The first time a user opens a mailbox after upgrading it may log some errors
such as:

---%<-------------------------------------------------------------------------
mbox sync: UID inserted in the middle of mailbox /var/mail/**** (4409 > 4237)
---%<-------------------------------------------------------------------------

The user may need to log out and log in again to see all of the messages in the
affected mailboxes. Note that this shouldn't happen unless the mbox already had
some errors. The new mbox parsing code just does better error checking.

Port Changes
------------

The port settings are different. The new settings are:

---%<-------------------------------------------------------------------------
# if you wish to just change IP address, change:
listen = 1.2.3.4
ssl_listen = 1.2.3.4

# if you wish to change ports also, use instead:
protocol imap {
  listen = *:143
  ssl_listen = *:993
}
protocol pop3 {
  listen = *:110
  ssl_listen = *:995
}
---%<-------------------------------------------------------------------------

Log Changes for POP before SMTP
-------------------------------

If you used <POP-before-SMTP> [PopBSMTPAndDovecot.txt], the log strings are
different. This should work with new versions:

---%<-------------------------------------------------------------------------
 $s =~ s/^... .. ..:..:.. .* dovecot: (pop3|imap)-login: Login: .+
rip=(\d+\.\d+\.\d+\.\d+),.*$/$2/i;
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2007-04-13 14:32)
