left header graphic
The Network People Banner
right header graphic

web this site

FreeBSD 4.6.2 Mail Toaster Tutorial (v2.2)
Author: Matt Simerson.
Last update: 08/29/2002. (ChangeLog)

The original of this document can be found on my server in Michigan or my other server in Atlanta.

This HOW-TO makes assumptions. 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. Installation order IS important. Build them in this order and your experience will be better.

Free support is NOT provided by the author. I you want my time, expect to pay for it. There is a mailing list available where I and a growing crowd of mail toaster owners hang out. You can browse the archives.

Contributions: Express ideas on the mailing list. If you are anxious to express your gratitude, feel free to purchase something from my gift list.


SMTP Mail Server (+SMTP-AUTH, TLS (SSL), tarpitting)
Virtual Domain Hosting
Virtual Domain Users
Mailing List
Web Based E-Mail (SSL, spell check, LDAP lookup)
Web Based Virtual Domain Administration
Spam Blocking

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, php, & perl: Secure HTTP server
OpenLDAP : LDAP client & server
vpopmail : Virtual Domain module
autorespond : Auto Responder
gdbm : Database routines
ispell : Spell checking for web mail
qmailadmin : Web Control Panel Interface
sqwebmail: Web based email
courier-IMAP: IMAP & POP3 servers

Install a bunch of required programs ( ispell, gdbm, setquota, autoconf, automake, expect, gnupg, maildrop, autorespond, qmailanalog, daemontools, openldap)

mkdir /usr/local/src; cd /usr/local/src
fetch http://matt.simerson.net/computing/mail/toaster/perl/toaster_setup.pl-1.4
chmod 755 toaster_setup.pl
./toaster_setup.pl -a install -s pre

Install Qmail (with a few hacks)

/usr/local/src/toaster_setup.pl -a install -s qmail -u postmaster -h mail.zone.com *
/var/qmail/bin/maildirmake /usr/share/skel/Maildir **
cd mail/qmail-1.03; make cert
vi /var/qmail/control/sql

* Don't forget to change mail.zone.com to your servers FQDN!
** Only necessary for /etc/passwd accounts

Install Apache www server + mod_php + mod_ssl + mod_perl

Apache build instructions

UCSPI-TCP: UNIX Client-Server Program Interface for TCP (with hacks)

cd /usr/local/src/mail
fetch http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
tar -xzf ucspi-tcp-0.88.tar.gz
fetch http://matt.simerson.net/computing/mail/toaster/ucspi-tcp-0.88-mysql+rss.patch
cd ucspi-tcp-0.88
patch -p1 < ../ucspi-tcp-0.88-mysql+rss.patch
make setup check

Install Ezmlm & Ezmlm-idx (Mailing List)

/usr/local/src/toaster_setup.pl -a install -s ezmlm

Vpopmail (Virtual Domain & POP)

cd /usr/local/src/mail
fetch http://www.inter7.com/devel/vpopmail-5.3.8.tar.gz
tar xzf vpopmail-5.3.8.tar.gz; cd vpopmail-5.3.8
./configure --enable-mysql=y --enable-default-domain=simerson.net \
--enable-roaming-users=y --enable-defaultquota=100000000S,10000C \
--enable-learn-passwords=y --enable-mysql-replication=y \
--enable-logging=p --enable-mysql-logging=y
vi vmysql.h

make all install

# crontab -e
9-59/10 * * * * /usr/local/vpopmail/bin/clearopensmtp 2>&1 > /dev/null

QmailAdmin (Web Control Interface)

cd /usr/local/src/mail
fetch http://www.inter7.com/devel/qmailadmin-1.0.6.tar.gz
fetch http://matt.simerson.net/computing/mail/toaster/qmailadmin-106-quotafix.txt
tar -xzf qmailadmin-1.0.6.tar.gz; cd qmailadmin-1.0.6
patch -p0 < ../qmailadmin-106-quotafix.txt
./configure --enable-cgibindir=/usr/local/www/cgi-bin
make install-strip

If you set up domains under /etc/passwd users you MUST do this:
chown root /usr/local/www/cgi-bin/qmailadmin

Sqwebmail (Web Based Email)

cd /usr/ports/mail/sqwebmail
make clean


cd /usr/local/src/mail
fetch http://download.sourceforge.net/courier/sqwebmail-3.3.3.tar.gz
tar -xvzf sqwebmail-3.3.3.tar.gz; cd sqwebmail-3.3.3
./configure --with-cachedir=/var/run/sqwebmail --enable-webpass=vpopmail --with-module=authvchkpw --enable-https --enable-logincache --enable-imagedir=/usr/local/www/data/webmail --without-authdaemon
make configure-check
vi authlib/Makefile sqwebmail/Makefile (add "-L/usr/local/lib/mysql -lmysqlclient" to LDFLAGS)
make check
make install (or upon reinstall) make install-exec
mkdir /var/run/sqwebmail; chown bin.bin /var/run/sqwebmail
chmod -R a+rx /usr/local/share/sqwebmail
# crontab -e
40 * * * * /usr/local/share/sqwebmail/cleancache.pl 2>&1 > /dev/null

chmod -R 755 /usr/local/www/data/webmail
cd /usr/local/share/sqwebmail
cp ldapaddressbook.dist ldapaddressbook
cp authdaemonrc.dist authdaemonrc

...if using authdaemon...
fetch -o /usr/local/etc/rc.d/sqwebmail.sh http://matt.simerson.net/computing/qmail/toaster/sqwebmail.txt
chmod 755 /usr/local/etc/rc.d/sqwebmail.sh
/usr/local/etc/rc.d/sqwebmail.sh start


cd /usr/local/src/mail
fetch http://download.sourceforge.net/courier/courier-imap-1.4.4.tar.gz
tar -zxvf courier-imap-1.4.4.tar.gz
setenv CFLAGS "-DHAVE_OPEN_SMTP_RELAY" (for tcsh)
export CFLAGS="-DHAVE_OPEN_SMTP_RELAY" (for bash)
cd courier-imap-1.4.4
./configure --prefix=/usr/local --exec-prefix=/usr/local --without-authldap \
--without-authshadow --with-authvchkpw --without-authcram \
--sysconfdir=/usr/local/etc/courier-imap \
--datadir=/usr/local/share/courier-imap \
--libexecdir=/usr/local/libexec/courier-imap \
--enable-workarounds-for-imap-client-bugs \
--disable-root-check --without-authdaemon
make install

/usr/local/src/toaster_setup.pl -a install -s courier
cd /usr/local/etc/courier-imap
vi pop3d.cnf imapd.cnf
vi quotawarnmsg
cd /usr/local/share/courier-imap; ./mkimapdcert; ./mkpop3dcert

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

mysql -u root -p
GRANT ALL PRIVILEGES ON vpopmail.* TO vpopmail@"hostname" IDENTIFIED BY 'password';
use vpopmail;
CREATE TABLE relay ( ip_addr char(18) NOT NULL default '',
timestamp char(12) default NULL,
name char(64) default NULL,
PRIMARY KEY (ip_addr)
mysql -u vpopmail -h db.domain.com -p (get this working before you continue)

~vpopmail/bin/vadddomain test.com [password]

Supervise/Svscan Startup

/usr/local/src/toaster_setup.pl -a install -s supervise

vi /var/qmail/supervise/smtp/run /var/qmail/supervise/send/run /var/qmail/rc

Fire up qmail

services start

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

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

OK, now 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
# ls ~vpopmail/domains/test.com/user/Maildir/*

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

Now we want to get our POP3-SSL and IMAP servers working. We can either reboot or start the servers manually:

imap start
pop3 start
imapssl start
pop3ssl start

Users can now get their email at the following addresses:

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

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



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

perl -MCPAN -e 'install Date::Parse'