#include <infodrom.style>
#include <debian.style>

<page title="Debian Tips">

<h1 align=center>Upgrading Cyrus IMAPd from version 2.1 to 2.2</h1>

<p>Upgrading Cyrus IMAPd on a sarge box can be little delightful.  In
this case the installed version is 2.1.18-1+sarge2, i.e. the last one
distributed in sarge.  The plan is to upgrade to version 2.2 that is
distributed via <code>sarge-backports</code>.</p>

<p>The Debian maintainer thankfully <a
href="https://mail.incase.de/viewcvs/branches/sarge-2.2.13/debian/README.Debian.database?rev=510&view=markup">\
documented</a> most steps required to upgrade form version 2.1 to
version 2.2 which includes a move from Berkeley DB 3.2 to Berkeley DB
4.3.  The plan includes to convert <code>deliver.db</code> and
<code>mailboxes.db</code> with the inhouse utility
<code>cvt_cyrusdb</code>.  However, the proposed command</p>

<p><pre>
   /usr/sbin/cvt_cyrusdb \
     /var/lib/cyrus/mailboxes.db db3 \
     /var/lib/cyrus/temp.db flat

  fatal error: unknown old backend
</pre></p>

<p>only results in the error message above.  This way no upgrade to
the new version is possible.  Upgrading the DB file with the command
<code>db4.3_upgrade</code> doesn't work either.  As mentioned the file
<code>tls_sessions.db</code> is not important and thus can be removed
and reconstructed automatically.</p>

<p>The other file <code>deliver.db</code> can be treated the same as
it only contains message ids of received mails.  Thus, a removed
database will only result in potentially duplicated mail for the
users.  In many cases this is acceptable if that's the price for the
upgrade.</p>

<p>The third file, however, <code>mailboxes.db</code> must not be
deleted.  It contains the names of all mailboxes Cyrus maintains
including new folders the users have created.  Quite important
information, it seems.</p>

<p>Since converting the DB files to the new format doesn't seem to be
possible in an easy way the file has to be regenerated from scratch.
Trashing it and re-creating all mailboxes by hand with the
<code>cyradm</code> utility may work for systems with only very few
mailboxes, but is not possible for large sites.</p>

<p>Fortunately, cyrus comes with a utility that can dump and restore
the mailbox file.  The <code>ctl_mboxlist</code> command must be run
from the Cyrus user and dumps the database with the switch
<code>-d</code>.  The resulting text file is used as input for the
program after the upgrade using the <code>-u</code> switch.</p>

<p><pre>
  /usr/sbin/ctl_mboxlist -d &gt; /tmp/mailboxes.txt

  [upgrade from 2.1 to 2.2]

  /usr/sbin/ctl_mboxlist -u &lt; /tmp/mailboxes.txt
</pre></p>

<p>Afterwards Cyrus starts again and the IMAP daemon is up and running
again.</p>

</page>

# Local variables:
# mode: indented-text
# end: