Upgrading to Vexim 2.3

This instruction will help you upgrade your existing Vexim installation to 2.3.

We suggest that you read this manual before starting the upgrade, to be aware in advance of any potential pitfalls.

Backup

First and foremost, backup all data so that you can revert to your current setup if something fails. This should comprise:

• the MySQL database (most likely vexim)
• the Exim configuration folder /etc/exim4/
• Vexim files (probably /var/www/vexim)

Information You Will Need

Version of Exim

Enter on command line: exim4 --version

Version of Vexim

If you don't remember the version you installed, have a look into your database (start this list from the top):

• if your users table doesn't contain the status column, and all the conditions below apply, you are running vexim 1.3 or earlier
• if you don't have the blocklists, domainalias and domains tables, and the conditions below apply, then your version is vexim 1.5
• if you don't have the groups and group_contents tables, then your version is vexim 2.0.1 (or 2.0)
• if your domains table has a complexpass column and your users table has clear and on_complexpass columns, but does not have a spam_drop column, you're using vexim 2.2RC1, 2.2 or 2.2.1
  • special case: if your users table has movedelete and on_rewritesubject columns, you're most likely using one of 2.2 versions with Arne Schirmacher's patch
• anything else is probably an interim checkout from version control. We hope that in this case you can figure out how to upgrade the version you are using yourself, but if not, feel free to ask for help on our mailing list.

Update Process

Stop Exim, the IMAP server and your webserver.

First update your database:

Database

In the folder setup/migrations/ you will find the migration scripts. You have to apply these sequentially, starting with the one upgrading your version to the next one and so on. For example, if you are currently running vexim 1.3, you have to apply the patch to migrate from 1.3 to 1.5, then from 1.5 to 2.0.1, and so on.

The last script (vexim_2.2_to_2.3_mysql.sql) will re-hash passwords for all users, which have clear and crypt fields in sync. By default, SHA-512 hashes will be used. If you want to use different hashes, open vexim_2.2_to_2.3_mysql.sql and define a different salt prefix instead of $6$. If you don't want password re-hashing to happen, just comment out this definition. If you have doubts, it is probably best to ask on our mailing list.

This script will also drop the clear field (where users' passwords are stored in clear text) from the database. If you believe this will cause you trouble, please contact us on the mailing list. Vexim has an option to store passwords in plain form (in which case their encrypted form is not stored), but we absolutely don't want to promote or endorse it.

There have been several patches to add features to Vexim and/or remove bugs. If you are using Arne Schirmacher's patch, uncomment these lines at the end of vexim_2.2_to_2.3_mysql.sql in order to migrate Arne's custom functionality. For other patches, please consult the mailing list as well.

To execute a script, run:

mysql -u vexim -p DATABASE_NAME < setup/migrations/SCRIPT_FILE_NAME

Exim Configuration

There is a new configuration file in docs/configure. Make a copy of it and update the copy with the configuration settings from your old exim4.conf (ip address, hostname, database credentials, exim user). Rename this copy to /etc/exim4.conf and try to restart Exim. If you personalized your exim4.conf, you'll have to add these changes again.

Important: For Exim version <4.82, please uncomment this line:

 OLD_HEADERS_REMOVE = yes

To increase security, we only allow user authentication via TLS, so you have to make sure that TLS certificates are properly installed:

tls_certificate = /etc/exim4/exim.crt
tls_privatekey = /etc/exim4/exim.key
tls_dhparam = /etc/exim4/dhparam.pem

To create DH-parameters, use openssl dhparam -out /etc/exim4/dhparam.pem 2048 (should be more than 1024 bit: https://weakdh.org/sysadmin.html). This can take some time.

Start Exim again:

service exim4 start

and check /var/log/exim4/paniclog for errors.

You can verify your SSL settings with the help of some external services, e.g. https://ssl-tools.net/mailservers.

Vexim

Copy the new vexim files from vexim/ to your web-root, e.g. /var/www/.

The configuration file format has changed, so backup the old one: mv vexim/config/variables.php vexim/config/variables.php.old copy the new one: cp vexim/config/variables.php.example vexim/config/variables.php edit vexim/config/variables.php and add the correct database credentials (and other settings from your original file).

Please note that the format for $dsn has changed in vexim 2.3 since we are now using PDO instead of PEAR-DB. You should NOT copy this variable from your old file.

Some features have been turned off by default but could be interesting for you. Have a look on some Optional Configuration settings.

POP3, IMAP etc.

If you used the clear field to verify passwords, you need to update your configuration. Furthermore we encourage you to enforce a secure connection (TLS/SSL) for authentication. Here we have some manuals for integrating Vexim with various third-party software. You will also find some manuals under docs/clients/ in the source distribution.