$Id: UPGRADING,v 1.1.2.1 2004/10/14 10:53:21 ilja Exp $

Upgrading from DBMail 1.2.x to DBMail 2.0.x
===========================================

When upgrading from DBMail 1.2.x to DBMail 2.0.x, please follow this guide:

REQUIREMENTS
============

* This guide, and the migration scripts assume you are running DBMail 1.2.x
currently. If you're running an earlier version, please make sure you
upgrade your database to DBMail 1.2.x first!

* If you are running MySQL, please check the server version. You can do this
by logging in to your MySQL server with the mysql command-line tool. Then
issue the cammand 'status', like so:

mysql> status

The response from MySQL looks like this (this one is running on an iBook):

--------------
mysql  Ver 12.22 Distrib 4.0.17, for apple-darwin7.2.0 (powerpc)

Connection id:          4
Current database:
Current user:           dbmail@localhost
SSL:                    Not in use
Current pager:          stdout
Using outfile:          ''
Server version:         4.0.17
Protocol version:       10
Connection:             Localhost via UNIX socket
Client characterset:    latin1
Server characterset:    latin1
UNIX socket:            /tmp/mysql.sock
Uptime:                 2 min 42 sec

Threads: 1  Questions: 7  Slow queries: 0  Opens: 6  Flush tables: 1  Open tables: 0  Queries per second avg: 0.043
--------------

The important line is: Server version:   4.0.17

The oldest MySQL version on which DBMail will work is 4.0.12.

STEPS IN UPGRADING
==================

* Make sure that DBMail 2.0 compiles on your system. Just run ./configure
with the right options (e.g. "./configure --with-pgsql") and make.
You now have the executables and libraries ready.

* Now comes the critical part. You old DBMail database has to be converted to
a 2.0 database, and your MTA configuration probably has to be changed a bit.

  - Make sure no changes are made to your database anymore. i.e. stop all 
    DBMail daemons, and make sure your MTA does not deliver to DBMail anymore.
    A simple way of doing the latter is to make your MTA not accept
    connections anymore. Other mailservers will assume your mailserver is 
    down and will try to resend messages later.

  - Make a backup of your current database. Really. Do this. 

  - Did you make a backup? Have you checked the backup worked?

  - Run the migration script in sql/mysql or sql/postgreql. This can take
    quite a long while, depending on your database size!

  - When the migration is finished, it's time to test it. Fire up the new
    DBMail POP3 or IMAP daemon from the source directory, and see if your
    mail is still where it's supposed to be. If it's not, something has 
    gone wrong. You can then continue running your old DBMail install 
    (first you have to reload your backupped database of course. You did 
    make that backup didn't you?). Please file a bug in the bug tracker on
    http://www.dbmail.org if things did not work out for you).

  - Remove old DBMail executables from /usr/local/bin (default) or 
    wherever you have installed it.

  - If everything works, please, you can issue 'make install' in the source
    directory. DBMail will now be installed (default is /usr/local/sbin for
    the executables). 

  - Adapt your MTA configuration to use the new executables. DBMail 1.2.x 
    puts the executables in /usr/local/bin by default. DBMail 2.0 puts them
    in /usr/local/sbin. You'll problaby have a reference to 
    /usr/local/bin/dbmail-smtp in your MTA config. Change this to
    /usr/local/sbin/dbmail-smtp.

  - Start the DBMail POP3 and/or DBMail IMAP daemons and make sure they
    work (look for your own mail for example).

  - Test your MTA installation. Make sure your MTA only allows connections
    from one machine (e.g. localhost) and send yourself an email. Check
    to see if it comes through.

  - If everything works, open up your MTA for connections from outside, and
    you're back in business!

If you experience any problems in the Upgrade, whether because of bugs, or 
because of a lack of information here, please make a note of it on the
dbmail mailinglist and/or in the bugtracker. We're always glad to improve
DBMail.

Ilja Booij
IC & S


