Postfix-Cyrus-Web-cyradm-HOWTO
Prev |  | Next

# 3. Getting and installing the software

Most of the software is included in your Linux distribution. I. e. SuSE is shipping Cyrus as far as I know since 7.1. Since SuSE 8.1, cyrus-imap 2.1 and sasl2 is included, and works. It is still recommended to compile Cyrus by yourself. SuSE does not ship a MySQL enabled Postfix.

| Deprecated packages for Debian stable and testing
| Debian users probably want to install packages provided by Debian. Unfortunately Debian stable (Woody) and testing (sarge) are using the deprecated version of the software used in this HOWTO. I tested the respective packages from Debian unstable (sid) and the are working. Please note, that the maintainers at Debian are very conservative. The software packages »postfix-mysql«, »libsasl2« and »cyrus21-imapd« are stable, even if they are only available in the »unstable« tree.

## 3.1. Getting and installing MySQL

### 3.1.1. Download

Origin-Site: http://www.mysql.com/downloads/

### 3.1.2. Building and installing

    cd /usr/local
    tar -xvzf mysql-4.0.18.tar.gz
    cd mysql-4.0.18

    ./configure \
    --prefix=/usr/local/mysql \
    --enable-assembler \
    --with-innodb \
    --without-debug

    make
    make install

    /usr/local/mysql/bin/mysql_install_db
    echo /usr/local/mysql/lib/mysql >> /etc/ld.so.conf
    ldconfig

    ln -s /usr/local/mysql/include/mysql /usr/include/mysql
    ln -s /usr/local/mysql/lib/mysql /usr/lib/mysql

To improve security, add a mysql-user on your system i.e. »mysql«, then

    chown -R mysql /usr/local/mysql/var

If you want to start MySQL automatically at boottime, copy `/usr/local/mysql/share/mysql/mysql.server` to `/etc/init.d/` for SuSE, for Redhat it is `/etc/rc.d/init.d` instead of `/etc/init.d/`. Further you need to add symbolic links to `/etc/init.d/rc3.d` for SuSE and `/etc/rc.d/rc3.d` for Redhat.

The following example is for SuSE Linux and should be easily changed for Redhat and other Linux distributions and commercial Unix systems.

    cp /usr/local/mysql/share/mysql/mysql.server /etc/init.d/
    ln -s /etc/init.d/mysql.server /etc/init.d/rc3.d/S20mysql
    ln -s /etc/init.d/mysql.server /etc/init.d/rc3.d/k08mysql

## 3.2. Getting and installing Berkeley DB

The Berkeley DB is a requirement for building Cyrus-SASL and Cyrus-IMAP. Some Systems comes with recent versions but without the header files installed. Please see your distributors CD/DVD to see if you can install the header files from a package. Usually this package is called bdb-devel.

The version that comes with GNU/Debian Linux is out of date, you will need to compile the most recent version instead. If you already installed Berkeley DB on your Debian Box, please uninstall it to prevent conflicts.

It is also very important, that Cyrus-SASL and Cyrus-IMAP is compiled with the same version of Berkeley DB or else you can run into problems.

| Berkeley DB versions
| I only tested version 4.0.x versions of bdb. Please let me know if you are successful with newer versions.

### 3.2.1. Download Berkeley DB

Origin-Site: http://www.sleepycat.com/update/snapshot/db-4.0.14.tar.gz

### 3.2.2. Building and installing Berkeley DB

    cd dist

    ./configure --prefix=/usr/local/bdb

    make
    make install

    echo /usr/local/bdb/lib >> /etc/ld.so.conf
    ldconfig

## 3.3. Getting and installing OpenSSL

### 3.3.1. Download OpenSSL

Origin-Site http://www.openssl.org

### 3.3.2. Building and installing

    cd /usr/local
    tar -xvzf openssl-0.9.7d.tar.gz

    cd openssl-0.9.7d

    ./config shared

    make
    make test
    make install

    echo "/usr/local/ssl/lib" >> /etc/ld.so.conf
    ldconfig

| Select your CPU to improve speed
| By default the Makefile generates code for the i486 CPU. You can change this by editing the `Makefile` after running config `shared`. Search for `-m486` and replace it i.e with `-march=athlon`

## 3.4. Getting and installing Cyrus SASL and IMAP

Building Cyrus SASL and IMAP from source is not a easy task. There are some prerequisites to be fulfilled, and lots of difficult authentication related stuff to be considered.

### 3.4.1. Download Cyrus SASL and Cyrus IMAP

Origin-Site: ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-sasl-2.1.18.tar.gz

Origin-Site: ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-imapd-2.2.3.tar.gz

### 3.4.2. Create the cyrus user

On most systems there is no cyrus user and mailgroup by default. Check for a free UID, usually daemons are running with UIDs less that 100. As example I am using UID 96 which is what SuSE has in the default `/etc/passwd`.

    groupadd mail
    useradd -u 96 -d /usr/cyrus -g mail cyrus
    passwd cyrus

### 3.4.3. Building and installing Cyrus SASL

    tar -xvzf cyrus-sasl-2.1.18.tar.gz
    cd cyrus-sasl-2.1.18

    ./configure \
    --enable-anon \
    --enable-plain \
    --enable-login \
    --disable-krb4 \
    --disable-otp \
    --disable-cram \
    --disable-digest \
    --with-saslauthd=/var/run/saslauthd \
    --with-pam=/lib/security \
    --with-dblib=berkeley \
    --with-bdb-libdir=/usr/local/bdb/lib \
    --with-bdb-incdir=/usr/local/bdb/include \
    --with-openssl=/usr/local/ssl \
    --with-plugindir=/usr/local/lib/sasl2

    make
    make install

    mkdir -p /var/run/saslauthd

    cd saslauthd
    make testsaslauthd
    cp testsaslauthd /usr/local/bin

    echo /usr/local/lib/sasl2 >> /etc/ld.so.conf
    ldconfig

The SASL library is installed in `/usr/local/lib/sasl2` but some programs are expecting SASL in `/usr/lib/sasl2`. So it is a good idea to create a symbolic link: ln -s /usr/local/lib/sasl2 /usr/lib/sasl2.

### 3.4.4. Building Cyrus-IMAP

    tar -xvzf cyrus-imapd-2.2.3.tar.gz
    cd cyrus-imapd-2.2.3

    export CPPFLAGS="-I/usr/include/et"

    ./configure \
    --with-sasl=/usr/local/lib \
    --with-perl \
    --with-auth=unix \
    --with-dbdir=/usr/local/bdb \
    --with-bdb-libdir=/usr/local/bdb/lib \
    --with-bdb-incdir=/usr/local/bdb/include \
    --with-openssl=/usr/local/ssl \
    --without-ucdsnmp \

    make depend
    make
    make install

### 3.4.5. Automatic startup script

If you wish to start the Cyrus IMAP daemon automatically after booting, you need a startup script. Place the following script in `/etc/init.d/`. For Redhat, it is `/etc/rc.d/init.d` instead of `/etc/init.d/`.

    #!/bin/bash
    #
    # Cyrus startup script

    case "$1" in
        start)
            # Starting SASL saslauthdaemon
            /usr/local/sbin/saslauthd -c -a pam&

            # Starting Cyrus IMAP Server
            /usr/cyrus/bin/master &
            ;;

        stop)

            # Stopping SASL saslauthdaemon
            killall saslauthd

            # Stopping Cyrus IMAP Server
            killall /usr/cyrus/bin/master

            ;;

        *)
            echo "Usage: $0 {start|stop}"
            exit 1
            ;;

    esac

If I get the time, I will provide a more sophisticated script, but this script works.

Now create the Symlinks in the runlevel directory (SuSE):

    ln -s /etc/init.d/cyrus /etc/init.d/rc3.d/S20
    ln -s /etc/init.d/cyrus /etc/init.d/rc3.d/K10

For Redhat:

    ln -s /etc/rc.d/init.d/cyrus /etc/rc.d/rc3.d/S20cyrus
    ln -s /etc/rc.d/init.d/cyrus /etc/rc.d/rc3.d/K10cyrus

### 3.4.6. Update Cyrus IMAPd

This section describes HOWTO update the IMAPd from version 2.1.x to 2.2.x

| Update is critical and can mean complete data loss
| Please test this procedure on a test/pre-production server first. Also have close look to `install-upgrade.html` that comes with the cyrus-imapd distribution. Please note, that you shoud plan a downtime for the production server to have the time to solve problems. Also note, that nobody I cannot take responsibility for the update procedure provided here

Cyrus changed the format of the dbd databases used for internal storage of mailboxlist flags etc.

A convert script comes with the distribution. The most important database is `/var/imap/mailboxes.db`. Without that database cyrus-imapd will NOT run. This requires a backup. Lets do a dump and a backup of the database.

    /etc/init.d/cyrus stop # be sure no cyrus process is running

    lsof /var/imap/mailboxes.db # be sure NO process is accessing the mailbox file

    su - cyrus
    /usr/cyrus/bin/ctl_mboxlist -d > /tmp/mailbox.db.dump
    cp /var/imap/mailboxes.db /var/imap/mailboxes.db.old

Convert the `/var/imap/mailboxes.db`

    /usr/cyrus/bin/cvt_cyrusdb /var/imap/mailboxes.db berkeley /var/imap/mailboxes.db.new skiplist
    mv /var/imap/mailboxes.db.new /var/imap/mailboxes.db

Convert all the »seen« databases:

    find /var/imap/user -name \*.seen -exec /usr/cyrus/bin/cvt_cyrusdb \{\} flat \{\}.new skiplist \; -exec mv \{\}.new \{\} \;

Converting the sieve scripts

    /usr/local/cyrus-imapd-2.2.3/tools/masssievec /usr/cyrus/bin/sievec

## 3.5. Getting and installing Postfix

### 3.5.1. Download

Origin-Site: http://www.postfix.org/ftp-sites.html

### 3.5.2. Creating a User-ID (UID) and Group-ID (GID) for postfix

Before you build and install postfix, be sure to create a »postfix« and a »postdrop« user and group if they do not exist on the system. First check for the groups. You can check this by grep postfix /etc/group and grep maildrop /etc/group

If there are no such groups and users, you just create them. Search for a free numeric UID and GID. In the following example I will use UID and GID 33333 for Postfix and 33335 for the maildrop UID and GID. These ID's correspond to other documents.

    groupadd -g 33333 postfix
    groupadd -g 33335 postdrop

    useradd -u 33333 -g 33333 -d /dev/null -s /bin/false postfix

### 3.5.3. Building and installing

The following section shows what you have to do if you installed MySQL from source as described above. If you installed MySQL from a binary package such as rpm or deb, then you have to change the include and library-flags to -I/usr/include/mysql and -L/usr/lib/mysql.

| Old MTA needs to be uninstalled
| It is important that you uninstall any sendmail version from RPM based systems. I suggest that you remove sendmail, and install Postfix instead. At least SuSE RPMs need a MTA. After installing the Postfix-RPM, just install Postfix over the RPM installation by following the HOWTO.

    tar -xvzf postfix-2.0.19.tar.gz

    cd postfix-2.0.19

    make makefiles 'CCARGS=-DHAS_MYSQL \
    -I/usr/local/mysql/include/mysql -DUSE_SASL_AUTH \
    -I/usr/local/include/sasl -I/usr/local/bdb/include' \
    'AUXLIBS=-L/usr/local/mysql/lib/mysql \
    -lmysqlclient -lz -lm -L/usr/local/lib -lsasl2 -L/usr/local/bdb/lib'
    make
    make install

During make install a few question are asked. Just pressing Enter should match your needs. For Redhat users it could be useful to enter `/usr/local/share/man`

Now you need to create some symbolic links to start Postfix automatically on system startup. The sample is for SuSE Linux, please consult your vendors manual for other distributions.

    ln -s /usr/sbin/postfix /etc/init.d/rc3.d/S14postfix
    ln -s /usr/sbin/postfix /etc/init.d/rc3.d/K07postfix

## 3.6. Getting and installing PAM

PAM is installed by default on almost all Linux distributions. I am not describing how to compile PAM by yourself, because it could break your system. Instead, I will describe how to install the package.

Users of a RPM based distribution can issue the following command:

    rpm -i pam-devel.rpm

Debian users can install the devel package with the following command:

    apt-get install libpam0g-dev

## 3.7. Getting and installing pam_mysql

### 3.7.1. Download

Origin-Site: http://sourceforge.net/projects/pam-mysql/

### 3.7.2. Installing

    tar -xvzf pam_mysql-0.5.tar.gz

    cd pam_mysql

If you have compiled mysql by yourself, check the `Makefile` and enter the correct path to your mysql libs and add the compiler flag `CFLAGS` `-I/path/to/mysql/include`.

    ifndef FULL_LINUX_PAM_SOURCE_TREE
    export DYNAMIC=-DPAM_DYNAMIC
    export CC=gcc
    export CFLAGS=-O2 -Dlinux -DLINUX_PAM \
           -ansi -D_POSIX_SOURCE -Wall -Wwrite-strings \
           -Wpointer-arith -Wcast-qual -Wcast-align -Wtraditional \
           -Wstrict-prototypes -Wmissing-prototypes -Wnested-externs -Winline \
           -Wshadow -pedantic -fPIC -I/usr/local/mysql/include
    export MKDIR=mkdir -p
    export LD_D=gcc -shared -Xlinker -x -L/usr/local/mysql/lib/mysql -lz
    endif

After customizing that file you an go ahead with the pam_mysql compile.

    make

    cp pam_mysql.so /lib/security

    [[ ! -d /var/lib/mysql ]] && mkdir /var/lib/mysql
    ln -s /tmp/mysql.sock /var/lib/mysql/mysql.sock

## 3.8. Getting and installing Web-cyradm

### 3.8.1. Download

Origin-Site: http://www.web-cyradm.org

### 3.8.2. Installing

    cd /usr/local/apache/htdocs

    tar -xvzf web-cyradm-0.5.4.tar.gz

    touch /var/log/web-cyradm.log
    chown nobody /var/log/web-cyradm.log

After unpacking web-cyradm, move it to a place in your webserver's documentroot.

Thats all. Now you need to configure the whole bunch of software.

Web-cyradm 0.5.4 is considered stable, and was released on 2003-12-05

Since web-cyradm uses PEAR for its database abstraction layer, you also need a recent copy of PEAR. This is included in recent PHP Versions. I strongly suggest to update PHP to 4.3.4, because a lot of important bugs have been fixed.

A frequent mistake is to forget to touch the logfile and change the owner to the Apache UID. This is usually »nobody« or »wwwrun«.

### 3.8.3. Create the databases and tables

Now we need to create the database and tables for Postfix and Web-cyradm and add a user to the database.

Web-cyradm comes with several MySQL scripts: `insertuser_mysql.sql` and `create_mysql.sql`. The first inserts the Database user to the database »mysql« and creates the database »mail«. The second creates the required tables and populates the database with an initial admin-user and the cyrus user.

The other scripts are used for incremental upgrading from older releases.

The password for the database user »mail« in this example is »secret«. Please insert whatever user and password you like.

The username for the initial superuser is »admin« with the password »test«.

| Change the default password!
| If a malicious user wants to gain unauthorized access to a system, the first attempt is always the default username and password supplied by the vendor. It is IMPORTANT that you change them in the scripts before applying them.

After customizing the username and password, apply the scripts:

    /usr/local/mysql/bin/mysql -u root -p < \
    /usr/local/apache/htdocs/web-cyradm/scripts/insertuser_mysql.sql

    /usr/local/mysql/bin/mysql mail -u mail -p < \
    /usr/local/apache/htdocs/web-cyradm/scripts/create_mysql.sql

### 3.8.4. Upgrading from 0.5.3 to 0.5.4

In version 0.5.4 there is a small database enhancement. You can upgrade your database by issuing the MySQL script that comes with the distribution.

    mysql mail -u mail -p < \
    scripts/upgrade-0.5.3-to-0.5.4_mysql.sql

Since Version 0.5.3 web-cyradm has full support for DES crypted passwords. You can use the php-script `migrate.php` to convert the users passwords from plain text to unix compatible crypt (DES).

| Migration from plain to crypt cannot be undone
| Be sure to have a recent backup of your database before doing anything with the migration script.

Prev | Home | Next
Technologies |  | Configuring MySQL