Nick's qmail Cookbook

Nick Vargish


Install MySQL

You may already have MySQL installed; if you do, there's no real need to install it again. I had problems getting vpopmail to work happily with versions in the 4.x series, but anything in the 3.x line should be fine. Try running /usr/bin/mysql to see if it's already installed.

You can download version 3.23.58 in a number of binary forms as well as source at the MySQL Product Archives.

Install qmail

Support utilities

Download ucspi-tcp: ucspi-tcp-0.88.tar.gz. Unpack it and cd into the source directory, then build and install it:

make setup check

Download daemontools: daemontools-0.76.tar.gz. Make a build directory, unpack the source into it, build and install:

mkdir daemontools
cd daemontools
tar xzf ../daemontools-0.76.tar.gz
cd admin/daemontools-0.76

qmail itself

Download qmail 1.03: qmail-1.03.tar.gz. Unpack it and change into the source directory.

Create qmail home directory:

mkdir /var/qmail

Create qmail ids:

groupadd nofiles
useradd -g nofiles -d /var/qmail/alias alias
useradd -g nofiles -d /var/qmail qmaild
useradd -g nofiles -d /var/qmail qmaill
useradd -g nofiles -d /var/qmail qmailp
groupadd qmail
useradd -g qmail -d /var/qmail qmailq
useradd -g qmail -d /var/qmail qmailr
useradd -g qmail -d /var/qmail qmails

Build and install the software:

make setup check

Set up the basic control files:


If you have trouble running config (perhaps due to name service issues), you can try this:

./config-fast `hostname`

Set up alias files for basic accounts:

(cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root)
chmod 644 ~alias/.qmail*

Create maildirs for local users who will be directly receiving mail, though in general it's easier to just set up a virtual domain for the local users. You will at least want to create one for root:

(cd ; /var/qmail/bin/maildirmake Maildir)
  su - $user -c "/var/qmail/bin/maildirmake Maildir"

Install an init script for the qmail system (qmail.init) and start it up:

chmod +x /etc/init.d/qmail.init
ln -s /etc/init.d/qmail.init /etc/rc3.d/S80qmail
/etc/init.d/qmail.init start

Install an init script for the qmail-smtp handler (qmail-smtp.init), but don't start it up yet:

chmod +x /etc/init.d/qmail-smtp.init
ln -s /etc/init.d/qmail-smtp.init /etc/rc3.d/S81qmail-smtp

I prefer to move sendmail out of the way (or you can use rpm to delete it completely with rpm -e --nodeps sendmail), and link in the qmail replacement:

mv /usr/lib/sendmail /usr/lib/sendmail.OLD
mv /usr/sbin/sendmail /usr/sbin/sendmail.OLD
ln -s /var/qmail/bin/sendmail /usr/sbin /usr/lib

Install vpopmail

(Version used: vpopmail-stable 5.4.10)

Download the vpopmail source from sourceforge and unpack it, cd into the source directory.

Create the user accounts:

groupadd -g 89 vchkpw
useradd -g vchkpw -u 89 -d /var/vpopmail vpopmail

You may have conflicts with a postfix user. If so, simply delete the postfix user and group (you won't be using postfix since you're installing qmail).

Create the MySQL database and grant the appropriate permissions to the vpopmail user:

mysql --password="MYSQL_ROOT_PASSWORD"

create database vpopmail;
grant select,insert,update,delete,create,drop 
  on vpopmail.* 
  to vpopmail@localhost identified by 'VPOP_DB_PASSWORD'; 

Run configure (replace POSTMASTER@YOUR.DOMAIN with an appropriate email address):

./configure --enable-roaming-users=y \
	    --enable-admin-email=POSTMASTER@YOUR.DOMAIN \
	    --enable-logging=p \
            --enable-ip-alias-domains=n \
	    --enable-passwd=n \
            --enable-clear-passwd=y \
	    --enable-many-domains=y \
            --enable-auth-logging=y \
	    --enable-auth-module=mysql \
            --enable-sql-logging=y \
	    --enable-valias=y \
            --enable-incdir=/usr/include/mysql \

Build and install vpopmail:

make install-strip

Create (or edit) /var/vpopmail/etc/vpopmail.mysql, which will contain the user and password for accessing the vpopmail database in MySQL:


Make sure the ownership and permissions are secure on the vpopmail.mysql file:

chown vpopmail /var/vpopmail/etc/vpopmail.mysql
chgrp vchkpw /var/vpopmail/etc/vpopmail.mysql
chmod 640 /var/vpopmail/etc/vpopmail.mysql

Install an init script for the pop service (vpopmail.init). Be sure to edit it so that your host's full address replaces YOUR.HOST.HERE. Make it executable and link it to the appropriate rc directory:

chmod +x /etc/init.d/vpopmail.init
ln -s /etc/init.d/vpopmail.init /etc/rc3.d/S83vpopmail

Set up the tcp.smtp file to permit SMTP relays for your local hosts:

cat > ~vpopmail/etc/tcp.smtp

Add a crontab entry that will keep the list of "roaming users" fresh. (Romaing user support: The server will act as an SMTP relay for addresses that have recently originated a successful POP login.):

40 * * * * /var/vpopmail/bin/clearopensmtp 2>&1 > /dev/null

Run the clearopensmtp program now, to initialize the database:


You can now start adding domains:

~vpopmail/bin/vadddomain DOMAIN.NAME POSTMASTER_PASSWORD

and users:

~vpopmail/bin/vadduser USER@DOMAIN.NAME USER_PASSWORD

Install Courier-IMAP

Courier Authentication Daemon

(Version used: 0.55, 2005-03-20)

Modern versions of the Courier-IMAP software require the installation of the Courier Authentication Daemon, so that's what we'll do first.

Download the latest stable version from the Courier download page, unpack it and cd into the directory.

Run the configure script, build and install it:

./configure --prefix=/opt/courier-imap
make install
make install-configure

Edit the file /opt/courier-imap/etc/authlib/authdaemonrc and look for the line that starts with authmodulelist=. Remove all the modules except authvchkpw so that it looks like this:


Install an init script for the authentication daemon (authdaemond.init). Make it executable and link it into the rc directories:

chmod +x /etc/init.d/authdaemond.init
ln -s /etc/init.d/authdaemond.ini /etc/rc3.d/S80authdaemond

Courier IMAP

(Version used: 4.0.2)

Download Courier-IMAP from the Courier download page. Unpack it and cd into the directory. Then configure, make, and install:

./configure --prefix=/opt/courier-imap --with-authvchkpw
make install
make install-configure

The default configuration should be fine, though you can increase the "MAXPERIP" value in /opt/courier-imap/etc/imapd to something higher (80 or 100).

Set up an init script for the IMAP server daemon:

cp /opt/courier-imap/libexec/imapd.rc /etc/init.d/imapd
chmod +x /etc/init.d/imapd
ln -s /etc/init.d/imapd /etc/rc3.d/S85imapd

Install squirrelmail

(This section may be slightly out of date, I'm currently using the development version 1.5.0, but configuration is basically unchanged.)

Download squirrelmail: squirrelmail-1.2.9.tar.gz. Unpack it, and move the resulting directory to its permanent location. Also, create and set up data and attachment directories. Under some apache configurations, replace "nobody" with "apache" (use ps to see what userid httpd is running under):

mv squirrelmail-1.2.9 /opt/squirrelmail
mkdir -p /var/squirrelmail/data
chgrp -R nobody /var/squirrelmail/data
chown -R nobody /var/squirrelmail/data
mkdir -p /var/squirrelmail/attach
chgrp -R nobody /var/squirrelmail/attach
chmod 730 /var/squirrelmail/attach
mkdir -p /var/squirrelmail/logs
chown -R nobody /var/squirrelmail/logs

Change to the squirrelmail directory and run the configure script to set up squirrelmail. Under "4. General Options" be sure to change the data and attachment directories to /var/squirrelmail/data and /var/squirrelmail/attach respectively. You will also want to make some changes in "1. Organization Preferences" and "2. Server Settings":

cd /opt/squirrelmail

If you want your users to be able to access squirrelmail as, add the following lines to your httpd.conf file:

Alias /mail /opt/squirrelmail/
<Directory "/opt/squirrelmail/">
  Options indexes followsymlinks
  order allow,deny
  allow from all

Make sure index.php is a valid index page by making sure the DirectoryIndex directive looks something like this:

<IfModule mod_dir.c>
    DirectoryIndex index.php index.html index.htm index.php3

Finally, if you are serving multiple domains, you can set things up by so that mail.this.domain and mail.that.domain bring up squirrelmail:

<VirtualHost *>
  ServerAlias mail.this.domain
  ServerAlias mail.that.domain

  ServerAdmin postmaster
  DocumentRoot /data/squirrelmail
  ErrorLog /var/squirrelmail/logs/error.log

Once the required changes have been made to httpd.conf, stop and start apache:

apachectl stop
apachectl start

Install qmailadmin

Install autorespond

Download autorespond: autorespond-2.0.2.tar.gz. Unpack it, build and install it:

make install

Install ezmlm and ezmlm/idx

Download ezmlm: ezmlm-0.53.tar.gz, and unpack it. Download the ezmlm/idx patch: ezmlm-idx-0.40.tar.gz, and unpack it. Next, merge the sources, build and install:

cp -R ezmlm-idx-0.40/* ezmlm-0.53/
cd ezmlm-0.53
patch < idx.patch
make man
make setup

Install qmailadmin itself

Download qmailadmin: qmailadmin-1.0.6.tar.gz. Unpack the source, and cd into the directory:

tar zvf qmailadmin-1.0.6.tar.gz
cd qmailadmin-1.0.6

Make directories for the qmailadmin files, then build and install qmailadmin:

mkdir -p /opt/qmailadmin/htdocs
mkdir -p /opt/qmailadmin/cgi-bin
./configure  --enable-htmldir=/opt/qmailadmin/htdocs \
    --enable-cgibindir=/opt/qmailadmin/cgi-bin \
make install

Add the following to your httpd.conf file:

Alias /qmailadmin /opt/qmailadmin/
<Directory "/opt/qmailadmin/">
  Options indexes followsymlinks
  order allow,deny
  allow from all

Replace existing services


First, disable the automatic startup of sendmail, stop the service, move the old sendmail binaries/links out of the way and replace them with the qmail version:

mv /etc/rc2.d/S80sendmail /etc/rc2.d/no.S80sendmail
mv /etc/rc3.d/S80sendmail /etc/rc3.d/no.S80sendmail
/etc/init.d/sendmail stop
mv /usr/sbin/sendmail /usr/sbin/sendmail.old
mv /usr/lib/sendmail /usr/lib/sendmail.old
ln -s /var/qmail/bin/sendmail /usr/sbin
ln -s /var/qmail/bin/sendmail /usr/lib

Next, start the qmail system and the qmail-smtp service:

/etc/init.d/qmail.init start
/etc/init.d/qmail-smtpd.init start

POP3 and IMAP services

You might need to disable the pop3 and imap services that runs out of xinetd:

mkdir /etc/xinetd.disable
mv /etc/xinetd.d/ipop3 /etc/xinetd.d/imap /etc/xinetd.disable
/etc/init.d/xinetd stop
/etc/init.d/xinetd start

Now start the vpopmail pop3 and the courier-imap imap servers:

/etc/init.d/vpopmail.init start
/etc/init.d/courier-imap.init start

Appendix A: Primary sites

qmail Home Page (mirror list); AT&T mirror site
daemontools home page
ucspi-tcp home page
Download qmail 1.03
Download ucspi-tcp 0.88
Download daemontools 0.76
MySQL Home Page
Downloads for 3.23.58
vpopmail Home Page
Downloads at
Courier-IMAP Home Page
Authlib Download

Appendix B: Changelog

7 April 2005

After well over three years of relatively happy operation, I've had to rebuild my mail system due to a fatal hard drive crash. I could probably have rescued the existing setup and replicated it on new hardware, but it seemed like a good opportunity to see how the landscape had changed since I last wrote this up.

As it turns out, a few things have indeed changed. Configuration for vpopmail and Courier-IMAP is quite different now, and in many ways simpler, though Courier-IMAP now requires the installation of the Courier Authlib package. There is a new packaged version of qmail available that rolls in some patches, but configuring it is basically the same as it has been for over a decade. MySQL has moved on to versions in the 4.x range, but these don't seem to work with vpopmail, which is happier with the 3.x series.

As I update the sections to reflect the changes, I am removing the download links to specific versions of each piece of software. Such moving targets do not age well, and as much as I would like to, I can't update this document frequently enough to catch each new version. Instead, I will note which version of the software I used on my system at the start of each section.

Last revised 7 April 2005