Qmail + vpopmail + CourierIMAP + sqwebmail + MySQL for FreeBSD 4.2 Tutorial (v1.6.3)
Written by Matt Simerson and last updated 3/27/2001.

This HOW-TO makes some assumptions. First it assumes that you are a moderately competent system administrator. It also assumes you run FreeBSD and you track the -stable source tree. PAY ATTENTION to software versions as listed below. Installation order IS important. These programs check and configure themselves for use with each other. Build them in this order and your experience will be better.

CAUTION: This version requires that the user is comfortable with hacking in C. If you aren't comfortable hacking around in the source code, then I recommend following the v1.3 or v1.5 instructions. Now I'll show you how to build a mail server with all the following features:

ChangeLog: v1.6 - SMTP relay table is entirely contained in a MySQL table. Previously the tcp.smtp.cdb file was still generated based upon the contents of a MySQL table. We have modified the tcpserver application to check a MySQL table (instead of a flat file) for each SMTP session to determine if a user's IP can relay or not. If the database connection fails, we allow the SMTP session anyway but don't allow relaying. Invoke tcpserver with the -S flag to utilize the new feature.

Also new in this version is the inclusion of one of my scripts I've written to manage my mail toaster. As my scripts mature they get used for more and end up becoming more portable as I use them in different environments. So, look for the maildomain script in this document and enjoy it.

SMTP E-Mail Server
POP3 Virtual/Local Domain Hosting
POP3 Virtual/Local Domain Users
AutoResponder
Mailing List
Web Based E-Mail (SSL)
Web Based Virtual/Local Domain/User Control Interface
Spell checking for Web based mail
Spam Blocking
SMTP/SEND logging
SMTP roaming with POP & IMAP AUTH
POP3 & POP3 SSL
IMAP & IMAP SSL

You will install the following programs:

qmail-1.03.tar.gz : qmail!
mysql-3.23 : Database engine
ucspi-tcp-0.88.tar.gz : Inetd replacement
daemontools-0.70.tar.gz : Useful tools for managing daemons
qmailanalog-0.70.tar.gz: Tools for compiling qmail logs into useful info.
ezmlm-idx-0.40.tar.gz: Mailing list management
apache-ssl: Secure HTTP server
OpenLDAP: LDAP server
vpopmail-4.9.8-1.tar.gz : Virtual Domain/POP module
autorespond-1.0.0.tar.gz: Auto Responder module
gdbm-1.8.0.tar.gz : Database routines
ispell: Gives users a spell check for web mail
qmailadmin-0.42.tar.gz : Web Control Interface
sqwebmail-1.2.5.tar.gz: Web mail interface
courier-IMAP-1.3.4: IMAP & POP3 servers

Install from the FreeBSD Packages/Ports Collection:

ispell
qmailanalog
gdbm
autorespond
setquota

Make Users & Groups for Vpopmail & Apache-SSL

# pw groupadd -n vchkpw -g 90
# pw useradd -n vpopmail -u 90 -g 90 -c Vpopmail-Master -d /usr/home/vpopmail -s /sbin/nologin
# pw groupadd -n www -g 91
# pw useradd -n www -u 91 -g 91 -c https -d /usr/local/www -s /sbin/nologin

Install Qmail (with a few hacks)

# cd /usr/local/src/mail
# wget http://cr.yp.to/software/qmail-1.03.tar.gz
# wget http://matt.simerson.net/computing/qmail/qmail-1.03-matt-toaster.patch
# tar -xvzf qmail-1.03.tar.gz
# cd qmail-1.03
# patch -p1 < ../qmail-1.03-matt-toaster.patch
# make setup
# ./config-fast domain.com (or read INSTALL.ctl for control file settings)
# echo "255" > /var/qmail/control/concurrencyremote
# chmod 644 /var/qmail/control/concurrencyremote
# echo "50" > /var/qmail/control/tarpitcount
# echo "5" > /var/qmail/control/tarpitdelay

Make Users & Directories for Logging and Special Modules

# mkdir /var/log/mail
# chown -R qmaill.wheel /var/log/mail
# chmod -R 750 /var/log/mail

# mkdir -p /var/qmail/supervise; cd /var/qmail/supervise
# mkdir -p smtp/log send/log pop3/log
# chmod +t smtp send pop3
# ln -s /var/qmail/supervise /service

Edit config files

#mkdir -p ~vpopmail/etc
# vi ~vpopmail/etc/tcp.smtp
127.0.0.1:allow,RELAYCLIENT=""
:allow

# echo email@addr.ess > /var/qmail/alias/.qmail-root
# echo email@addr.ess > /var/qmail/alias/.qmail-postmaster
# echo email@addr.ess > /var/qmail/alias/.qmail-mailer-daemon

# /var/qmail/bin/maildirmake /usr/share/skel/Maildir ( necessary if using /etc/passwd accounts)

MySQL Database Engine

# cd /usr/ports/databases/mysql323-server
# make install clean

Install UNIX Client-Server Program Interface for TCP

# cd /usr/local/src
# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
# tar -xzf ucspi-tcp-0.88.tar.gz
# wget http://matt.simerson.net/computing/qmail/ucspi-tcp-0.88-mysql.patch
# cd ucspi-tcp-0.88
# patch -p1 < ../ucspi-tcp-0.88-mysql.patch
# make setup check

# vi /var/qmail/control/sql
server sql.mailserver.com
port 3306
database vpopmail
table relay
user vpopmail
pass secret
time 1800

Daemon Tools (Useful tools)

# cd /usr/ports/sysutils/daemontools
# make install clean

Install Ezmlm & Ezmlm-idx (Mailing List)

# cd /usr/ports/mail/ezmlm-idx
# make -DWITH_MYSQL install
# cp work/ezmlm-0.53/ezmlmrc /usr/local/bin
# make clean

Install Apache-modssl www server

# cd /usr/ports/www/apache13-modssl
# make
# make certificate TYPE=custom
# make install clean
# vi /usr/local/etc/apache/httpd.conf

Fire up the web server and fix any problems.

# /usr/local/sbin/apachectl startssl

OpenLDAP

# cd /usr/ports/net/openldap
# make install clean

Vpopmail (Virtual Domain & POP)

# mkdir /usr/local/src; cd /usr/local/src
# wget http://www.inter7.com/vpopmail/vpopmail-4.9.8-1.tar.gz
# tar xvzf vpopmail-4.9.8-1.tar.gz
# wget http://matt.simerson.net/computing/qmail/matt-vpopmail-4.9.8-1-patch.txt
# cd vpopmail-4.9.8-1
# patch -p1 < ../matt-vpopmail-4.9.8-patch.txt
# vi vopen_smtp.h
# autoconf
# ./configure --enable-roaming-users=mysql --enable-logging=y --enable-relay-clear-minutes=60 --enable-hardquota=100000000
# make
# make install-strip
# crontab -e
9-59,10 * * * * /usr/home/vpopmail/bin/clearopensmtp 2>&1 > /dev/null
# ln -s ~vpopmail/doc/man_html /usr/local/www/htdocs/vpopmail

Now you can point your web browser at https://host.yourdomain.com/vpopmail and see the spiffy documentation that comes with vpopmail. Since your test certificate isn't signed by a CA you'll have to approve it manually. Older versions of IE didn't deal well with new certificates.

Qmailadmin (Web Control Interface)

# cd /usr/local/src
# wget http://www.inter7.com/qmailadmin/qmailadmin-0.42.tar.gz
# ./configure --enable-htmldir=/usr/local/www/htdocs --enable-cgibindir=/usr/local/www/cgi-bin
# make install-strip
# (on reinstalls) cp qmailadmin /usr/local/www/cgi-bin

The reason you might want to simply copy the qmailadmin binary to the cgi-bin directory is that the installer will clobber your customized html.

OK, I told you it gets better, now point your web browser at http://host.yourdomain.com/cgi-bin/qmailadmin. Pretty cool eh? You can't do much because you haven't defined any virtual domains yet but hang in there. :-)

Sqwebmail (Web Based Email Checking)

# wget http://download.sourceforge.net/courier/sqwebmail-1.2.5.tar.gz
# tar -xvzf sqwebmail-1.2.5.tar.gz; cd sqwebmail-1.2.5
# ./configure --with-cachedir --enable-webpass=vpopmail --with-module=authvchkpw --enable-https --enable-logincache
# make configure-check
# make check
# make install (or upon reinstall) make install-exec
# mkdir /var/run/sqwebmail; chown bin.bin /var/run/sqwebmail
# crontab -e
40 * * * * /usr/local/share/sqwebmail/cleancache.pl 2>&1 > /dev/null

# chmod -R 755 /usr/local/www/htdocs/webmail
# chmod -R a+rx /usr/local/share/sqwebmail

Courier-IMAP

# cd /usr/local/src
# wget http://download.sourceforge.net/courier/courier-imap-1.3.6.tar.gz
# tar zxvf courier-imap-1.3.6.tar.gz; cd courier-imap-1.3.6
# ./configure --prefix=/usr/local --exec-prefix=/usr/local --without-authldap --disable-root-check --with-ssl --with-dyn-mysql=/usr/local/lib/mysql
# make
# make install-strip
# cd /usr/local/share; ./mkimapdcert; ./mkpop3dcert
# cd /usr/local/etc
# cp pop3d.dist pop3d; vi pop3d (change AUTHMODULES="authvchkpw"
# cp pop3d-ssl.dist pop3d-ssl
# cp imapd.dist imapd; vi imapd (change AUTHMODULES="authvchkpw"
# cp imapd-ssl.dist imapd-ssl

At this point in time, we'll start to add, remove and edit configuration files. We will also accomplish a number of other fun things.

Edit DNS zone file - You will need to get the dns properly configured for each domain you want to collect mail for. If your dns records are incorrect you will likely have problems with mail routing. For some helpful DNS links have a look at my dns links.

Adding Mail Domains

# ~vpopmail/bin/vadddomain test.com [password-for-postmaster(test)]

vadddomain will modify the following qmail files (default locations used):

/var/qmail/control/locals
/var/qmail/control/rcpthosts
/var/qmail/control/morercpthosts (if rcpthosts > than 50 lines)
/var/qmail/control/virtualdomains
/var/qmail/users/assign
/var/qmail/users/cdb

It will also create a domains directory

~vpopmail/domains/domain.com
~vpopmail/domains/domain.com/postmaster/Maildir ...
~vpopmail/domains/domain.com/vpasswd
~vpopmail/domains/domain.com/vpasswd.cdb

Then it will send a kill -HUP signal to qmail-send telling it to re-read the control files.

OK, now it's time to get qmail up and running. We're going to create a bunch of startup files that the daemontools package will monitor for us. Should one croak it'll restart it and it also gives us the ability to limit the daemons and give them some instructions on how to behave.

Supervise/Svscan Startup

# cd /var/qmail/supervise
# vi smtp/run

#!/bin/sh
PATH=/var/qmail/bin:/usr/local/bin:/usr/bin:/bin
export PATH
QMAILUID=`id -u qmaild`
NOFILESGID=`id -g qmaild`
exec softlimit -m 2000000 tcpserver -S -R -H -c100 -x /usr/home/vpopmail/etc/tcp.smtp.cdb \
-u $QMAILUID -g $NOFILESGID 0 smtp rblsmtpd qmail-smtpd splogger smtpd

# chmod 751 smtp/run
# touch smtp/log/run smtp/log/down
# chmod 751 smtp/log/*
# vi send/run

#!/bin/sh
exec /var/qmail/rc

# chmod 751 send/run
# vi send/log/run

#!/bin/sh
PATH=/var/qmail/bin:/usr/local/bin:/usr/bin:/bin
export PATH
exec setuidgid qmaill multilog t s1000000 n20 /var/log/mail/send 2>&1

# chmod 751 send/log/run
# vi pop3/run

#!/bin/sh
PATH=/var/qmail/bin:/usr/local/bin:/usr/bin:/bin
export PATH
exec tcpserver -R -H -c100 0 pop3 qmail-popup pop.safeserver.com \
/usr/local/vpopmail/bin/vchkpw qmail-pop3d Maildir splogger pop3

#!/bin/sh
exec env - PATH="/var/qmail/bin:$PATH" \
qmail-start ./Maildir/

Fire up qmail

# qmail start

What you should see in the process list:
# ps au

USER PID TT STAT STARTED TIME COMMAND
root 33322 p1 S 11:14PM 0:00.02 svscan
root 33323 p1 I 11:14PM 0:00.01 supervise send
root 33324 p1 I 11:14PM 0:00.01 supervise log
root 33325 p1 I 11:14PM 0:00.01 supervise smtp
root 33326 p1 I 11:14PM 0:00.01 supervise log
qmaill 33338 p1 I 11:14PM 0:00.00 multilog t s1000000 n20 /var/log/mail/send

OK, now your system is up and running and you're ready to have some real fun. Point a web browser at http://mail.domain.com/cgi-bin/qmailadmin. Log in with postmaster, test.com, and the test password. Add a user named "user". Time to send some email:

# mail user@test.com
Subject: test
test
.
# ls ~vpopmail/domains/test.com/user/Maildir/*

You should see a file in the new directory. If not, tail /var/log/mail/send/current and figure out why.

Now we want to get our POP3-SSL and IMAP servers working. Install the startup scripts in /usr/local/etc/rc.d:

# cp /usr/local/libexec/imapd.rc /usr/local/etc/rc.d/imapd.sh
# cp /usr/local/libexec/imapd-ssl.rc /usr/local/etc/rc.d/imapd-ssl.sh
# cp /usr/local/libexec/pop3d-ssl.rc /usr/local/etc/rc.d/pop3d-ssl.sh

Once installed we'll make symbolic links to the scripts for easy administration:

# ln -s /usr/local/etc/rc.d/imapd.sh /usr/local/sbin/imap
# ln -s /usr/local/etc/rc.d/imapd-ssl.sh /usr/local/sbin/imapssl
# ln -s /usr/local/etc/rc.d/pop3d-ssl.sh /usr/local/sbin/pop3ssl

Now we can either reboot or start the servers manually:

# imap start
# imapssl start
# pop3ssl start

Users can now get their email at the following addresses:

# pop3://mail.domain.com
# imap://mail.domain.com
# imaps://mail.domain.com
# http://mail.domain.com/cgi-bin/sqwebmail (redirects to https)
# https://mail.domain.com/cgi-bin/sqwebmail

Domain administrators can add/edit/delete users, mailing lists, autoresponders, mail forwarding, and aliases by logging into the qmailadmin interface:

# http://mail.domain.com/cgi-bin/qmailadmin
# https://mail.domain.com/cgi-bin/qmailadmin

SYSTEM ADMIN stuff.

maildomain perl script - Front end to nearly everything you can do with the vpopmail programs.

Convert Multilog date stamps to human readable date stamps

# tai64nlocal < logfile > qmaillog.tmp

Statistics about your mail queue:

Feed your qmail-send output through matchup and pipe it through a stats processor:
# /usr/local/qmailanalog/bin/matchup < /var/log/mail/send/current | /usr/local/qmailanalog/bin/z*
where z* is one of the following
# zddist, zdeferrals, zfailures, zoverall, zrecipients, zrhosts, zrxdelay, zsenders, zsuccesses, zsuids

Modify the HTML interface:

Sqwebmail: html temples live in /usr/local/share/sqwebmail/html/en-us/
qmailadmin: html templates live in /usr/local/share/qmailadmin/html/

Man pages:

vpopmail: http://mail.domain.com/vpopmail/
maildrop: http://mail.domain.com/maildrop