new Qmail VMailMgr and Courier-Imap HOWTO

Dan Kuykendall <dan@kuykendall.org> v1.2, 19 April 2000 This document is about building a mail server that will support virtual domain hosting and provide smtp, pop3 and imap services, using a powerful alternative to sendmail. Introduction

Before you start reading: I am not a native speaker, so there are probably spelling/grammatical errors in this document. Feel encouraged to inform me of mistakes.

What is Qmail and why should I use it?

Here is the authors (Dan Bernstein) blurb: Qmail is a secure, reliable, efficient, simple message transfer agent. It is meant as a replacement for the entire sendmail-binmail system on typical Internet-connected UNIX hosts. Secure: Security isn't just a goal, but an absolute requirement. Mail delivery is critical for users; it cannot be turned off, so it must be completely secure. (This is why I started writing qmail: I was sick of the security holes in sendmail and other MTAs.) Reliable: qmail's straight-paper-path philosophy guarantees that a message, once accepted into the system, will never be lost. qmail also supports maildir, a new, super-reliable user mailbox format. Maildirs, unlike mbox files and mh folders, won't be corrupted if the system crashes during delivery. Even better, not only can a user safely read his mail over NFS, but any number of NFS clients can deliver mail to him at the same time. Efficient: On a Pentium under BSD/OS, qmail can easily sustain 200000 local messages per day---that's separate messages injected and delivered to mailboxes in a real test! Although remote deliveries are inherently limited by the slowness of DNS and SMTP, qmail overlaps 20 simultaneous deliveries by default, so it zooms quickly through mailing lists. (This is why I finished qmail: I had to get a big mailing list set up.) Simple: qmail is vastly smaller than any other Internet MTA. Some reasons why: (1) Other MTAs have separate forwarding, aliasing, and mailing list mechanisms. qmail has one simple forwarding mechanism that lets users handle their own mailing lists. (2) Other MTAs offer a spectrum of delivery modes, from fast+unsafe to slow+queued. qmail- send is instantly triggered by new items in the queue, so the qmail system has just one delivery mode: fast+queued. (3) Other MTAs include, in effect, a specialized version of inetd that watches the load average. qmail's design inherently limits the machine load, so qmail-smtpd can safely run from your system's inetd. Replacement for sendmail: qmail supports host and user masquerading, full host hiding, virtual domains, null clients, list-owner rewriting, relay control, double-bounce recording, arbitrary RFC 822 address lists, cross-host mailing list loop detection, per-recipient checkpointing, downed host backoffs, independent message retry schedules, etc. In short, it's up to speed on modern MTA features. qmail also includes a drop-in ``sendmail'' wrapper so that it will be used transparently by your current UAs.

What is VMailMgr and why should I use it?

VMailMgr is:

A password checking interface between qmail-popup and qmail-pop3d which replaces the usual checkpassword, as well as an authentication module for Courier IMAP, that provide access to the virtual mailboxes by one of three methods: IP-based virtual server access (invisible to the POP3 user) username-based access (username-virtualuser) hostname-based access (virtualuser@virtual.host or virtualuser:virtual.host) You should use it if:

You prefer to have the users manage their own domains email accounts, and store their email in their own home dir. (This makes setting up disk space quotas much easier)

What is Courier-imap and why should I use it?

Courier-IMAP is:

A server that provides IMAP access to Maildir mailboxes. This IMAP server does NOT handle traditional mailbox files (/var/spool/mail, and derivatives), it was written for the specific purpose of providing IMAP access to Maildirs. You should use it because:

By default Qmail uses the newer more efficient Maildir format for storing email, and Courier-imap is the only imap server I am aware of that supports Maildir. So in short, if you use Qmail, and want imap support, you have to use it.

Description of the components

The email system you hopefully will get after having read this HOWTO is composed of several parts, the patched Qmail rpms are key to using this document. I recommend using the software versions I tried, they will probably compile without many problems and result in a fairly stable daemon. If you are courageous, you can try to compile all the latest-stuff-with-tons-of-new-features, but don't blame me if something fails ;-). However, you may report other working configurations to be included in future versions of this document. All of the steps were tested on a RedHat Linux 6.2 box, so the HOWTO is somewhat specific, but you should be able to use it for other linux distributions as well.

You do not necessarily have to install in all components. I tried to structure this HOWTO so that you can skip the parts you are not interested in.

The document is neither a user manual to Qmail, VMailMgr nor Courier-imap. Its prime intention is to save email admins some headaches when installing their server and to do my little contribution to the linux community.

Working configurations

Though this document is new, I am pretty confident that it can help you get your email system up and running. Combinations that work for me are: RedHat 6.2, Linux 2.2.14, Qmail 1.03+patches-12, VMailMgr 0.96.5, Courier-imap 0.31 Mandrake 7.0, Linux 2.2.13, Qmail 1.03+patches-12, VMailMgr 0.96.5, Courier-imap 0.31 History

This document was started on April 18, 2000 by Dan Kuykendall after several installs of Qmail and VMailMgr. Then even more setups when Courier-imap support was ready.

New versions

The newest version of this can be found on my homepage in its SGML source. Other versions may be found in different formats at the LDP homepage .

Comments

Comments on this HOWTO may be directed to the author Dan Kuykendall ().

Version History

v0.1 (April 18, 2000)

Preview version, wasn't in HOWTO format.

v1.0 (April 18, 2000)

Minor corrections. Added details and put into HOWTO format.

v1.1 (April 19, 2000)

Minor corrections. Restructured RPM install step. Added source compile and install steps.

v1.2 (April 19, 2000)

Minor corrections. Fixed source compile locations and install steps. Added source compile and install steps.

v1.3 (April 19, 2000)

Minor corrections. Built proper SGML version.

Copyrights and Trademarks

This manual may be reproduced in whole or in part, without fee, subject to the following restrictions:

The copyright notice above and this permission notice must be preserved complete on all complete or partial copies Any translation or derived work must be approved by the author in writing before distribution. If you distribute this work in part, instructions for obtaining the complete version of this manual must be included, and a means for obtaining a complete version provided. Small portions may be reproduced as illustrations for reviews or quotes in other works without this permission notice if proper citation is given.

Exceptions to these rules may be granted for academic purposes: Write to the author and ask. These restrictions are here to protect us as authors, not to restrict you as learners and educators. Any source code (aside from the SGML this document was written in) in this document is placed under the GNU General Public License, available via anonymous FTP from .

Acknowledgements and Thanks

Thanks to everyone that gave comments as I was writing this. This includes Bruce Guenter and other members of the vmailmgr-discuss list.

Component installation Preparations

You have two options Get and compile source rpms. This has the benefit of being able to review the source before compiling, and compiling for your specific setup. Or simply get the binary rpms. This has the benefit of simplicity, and not having to worry about having the necessary libraries installed. I recommend using Bruce Guenter's rpm releases, since they are well patched, and its what I used for building my systems.

Get source rpms

You will need: ucspi-tcp-0.88-1.src.rpm - daemontools-0.70-1.src.rpm - supervise-scripts-2.4-1.src.rpm - qmail-1.03+patches-12.src.rpm - vmailmgr-0.96.5-1.src.rpm - courier-imap-0.31.tar.gz - For Courier-imap you must build the source rpm from the tar file (instructions will follow).

Get binary rpms

Qmail does not come in binary form. Such packages are explicitly disallowed by the author of Qmail, and frustrating as it may be, I understand his reasoning.

Courier-imap does not come in binary form, unless you want to use the one I built. If you want mine, email me, and I will send it.

VMailMgr does not come in binary form that supports Courier-imap, unless you want to use the one I built. If you want mine, email me, and I will send it. ucspi-tcp-0.88-1.i386.rpm - daemontools-0.70-1.i386.rpm - supervise-scripts-2.4-1.i386.rpm - qmail-1.03+patches-12.src.rpm - vmailmgr-0.96.5-1.src.rpm - courier-imap-0.31.tar.gz - For Courier-imap you must build the binary rpm from the tar file (instructions will follow) or email me for my binary rpm.

Get tarred sources (for non-RPM users)

If your system does not have, or you do not use RPMS, you can install from source. ucspi-tcp-0.88.tar.gz - daemontools-0.70.tar.gz - supervise-scripts-2.4.tar.gz - qmail-1.03.tar.gz - (*) vmailmgr-0.96.5.tar.gz - courier-imap-0.31.tar.gz - (*) There may be minor differences in these instructions due to the use of the standard Qmail package. Please review the documentation for Qmail and VMailMgr if any of the files deviates from my instructions.

Install support packages Install with RPMS Compiling SRC.RPM's

Simply run the following command for each package rpm --rebuild <package.src.rpm> -Example- rpm --rebuild ucspi-tcp-0.88-1.src.rpm rpm --rebuild daemontools-0.70-1.src.rpm rpm --rebuild supervise-scripts-2.4-1.src.rpm

Installing RPM's

If you compiled the source rpms, the binaries will be located in /usr/src/redhat/RPMS/i386/ or something similar. Simply run the following command for each package rpm -ivh <location>/<package.i386.rpm> -Example- rpm -ivh /usr/src/redhat/RPMS/i386/ucspi-tcp-0.88-1.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/daemontools-0.70-1.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/supervise-scripts-2.4-1.i386.rpm

Install with source

Run the following commands for each package (As non-root user) tar zxf cd ./configure make (As root) make setup check (for ucspi-tcp and daemontools) or make install (for supervise-scripts) -Example- (As non-root user) tar zxf supervise-scripts-2.4.tar.gz cd supervise-scripts-2.4 ./configure make (As root) make setup check or make install

Install Qmail Install with RPMS

Compiling SRC.RPM's

Simply run the following command rpm --rebuild -Example- rpm --rebuild qmail-1.03+patches-12.src.rpm Installing RPM's

After compiling the source rpms, the binaries will be located in /usr/src/redhat/RPMS/i386/ or something similar. Simply run the following command for each package rpm -ivh / -Example- rpm -ivh /usr/src/redhat/RPMS/i386/qmail-1.03+patches-12.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/qmail-pop3d-1.03+patches-12.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/qmail-qmqpd-1.03+patches-12.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/qmail-qmtpd-1.03+patches-12.i386.rpm rpm -ivh /usr/src/redhat/RPMS/i386/qmail-smtpd-1.03+patches-12.i386.rpm * note start * - Remove sendmail and any dependant applications prior to installing Qmail - by running the following command for each package - rpm -e * - - On my system I had to remove sendmail, so I typed - rpm -e sendmail * note end *

Install with source

As of this writing Bruce Guenter has not released a tar.gz package of his patched qmail. So until Bruce does this, I am having you download the standard Qmail package, and forcing you to read the included INSTALL file.

Installing the standard build may cause minor differnces in the config, one example that comes to mind is that the init scripts are named differently. This should not cause too much confusion, I just want you to be aware.

Run the following command (As non-root user) tar zxf cd (Now read the INSTALL file and follow the steps to install Qmail) -Example- (As non-root user) tar zxf qmail-1.03.tar.gz cd qmail-1.03 vi INSTALL (Read and follow steps)

Install Courier-imap Install with RPMS Compiling SRC.RPM's

Build the courier-imap rpms from the tar file rpm -ta courier-imap-0.31.tar.gz * note start * - This errors out if you compile as root, but if your not root you - wont have permissions to /usr/src/redhat. You will want to build as a - non-root user, so create a ".rpmmacros" file (for rpm v3 and later) in - your home directory containing the line "%_topdir /path/to/home/redhat". - Then create your own "redhat" directory containing all the subdirs that - /usr/src/redhat contains. - You should never build RPMs as root unless you have to. * note end * * I will mention again, that I have built the binaries, and if you email me * * at dan@kuykendall.org, I will email them back to you. * Installing RPM's

After compiling the source rpms, the binary will be located in /usr/src/redhat/RPMS/i386/ or something similar. Simply run the following command for each package rpm -ivh / -Example- rpm -ivh /usr/src/redhat/RPMS/i386/courier-imap-0.31-1.i386.rpm Install with source

Run the following command (As non-root user) tar zxf cd ./configure make (As root) make install -Example- (As non-root user) tar zxf courier-imap-0.31.tar.gz cd courier-imap-0.31 ./configure make (As root) make install

Install VMailMgr

At the time of this writing Bruce had not released a binary version of VMailMgr that included Courier-imap support. This means until the next version of VMailMgr is release, you will be required to build the RPMS yourself. Install with RPMS Compiling SRC.RPM's

Now for the fun part, since VMailMgr needs the courier-imap sources during its compile to build the auth lib, I had to take the following steps. (please edit to suit your environment) 1) copy the courier-imap-0.31.tar.gz to non-root users home dir cp courier-imap-0.31.tar.gz ~user1/ 2) with my user account: untar, run config and make su user1 cd ~/ tar zxf courier-imap-0.31.tar.gz cd courier-imap-0.31 ./configure make 3) Install the VMailMgr sources and modify the spec file to support courier-imap rpm -ivh VMailMgr-0.96.5-1.src.rpm edit /usr/src/redhat/SPECS/VMailMgr-0.96.5.spec on the ./configure line (line 49) add the following text to the end --with-courier-imap=/home/user1/courier-imap-0.31/ 4) Compile VMailMgr based on the modified spec file rpm -bb /usr/src/redhat/SPECS/VMailMgr-0.96.5.spec * I will mention again, that I have built the binaries, and if you email me * * at dan@kuykendall.org, I will email them back to you. * Installing RPM's

Since VMailMgr needs the courier-imap sources during its compile to build the auth lib, and since your using the compiling source, you will need to have kept your courier-imap sources from where you compiled it. If you deleted them, redo the steps up to the make command.

Run the following command (As non-root user) tar zxf cd ./configure --with-courier-imap= make (As root) make install -Example- (As non-root user) tar zxf vmailmgr-0.96.5.tar.gz cd vmailmgr-0.96.5 ./configure --with-courier-imap=/home/user1/courier-imap-0.31/ make (As root) make install That should do it.

Putting it all together Basic Qmail config

You will need to add your domains to the /var/qmail/control/virtualdomains file in the following format as is normal with qmail and VMailMgr. domain1.com:user1 For more detailed setup and config documentation visit the Qmail website and the VMailMgr website

Tell Qmail to use VMailMgr for authentication

By default qmail uses checkpassword for authentication, to tell Qmail to use VMailMgr for authentication type the following command: echo checkvpw > /var/qmail/control/checkpassword Setup Courier-imap for VMailMgr

Copy the VMailMgr auth libs to courier's directory cp /usr/bin/authvmailmgr /usr/lib/courier-imap/libexec/authlib/ Edit /usr/lib/courier-imap/etc/imapd.config and add authvmailmgr as the first entry in AUTHMODULES

For more detailed setup and config documentation visit the Courier-imap website

Setup virtual domain with VMailMgr

With the user account that will be managing the domain go to their home dir and type: vsetup This will setup the users home dir with the necessary structure to handle incoming email. You will probably want to create a email account by typing vadduser emailuser For more detailed setup and config documentation visit the VMailMgr website

Starting the daemons

Start Qmail daemons /etc/rc.d/init.d/qmail start /etc/rc.d/init.d/pop3d start /etc/rc.d/init.d/smtp start /etc/rc.d/init.d/qmqpd start (optional) /etc/rc.d/init.d/qmtpd start (optional) Start VMailMgr daemon /etc/rc.d/init.d/vmailmgrd start Start Courier-imap damon /etc/rc.d/init.d/courier-imap start

Some considerations left

Qmail and the Maildirs may cause some email apps that run locally to not work. Visit the Qmail website for details on email apps that have been patched to work with Maildirs.

Courier-imap is not as widely used as Cyrus or UWash imap servers. As such, you may suffer from minor incompatibilities. Courier-imap is extremely well written, and tries to comply with the imap definition even if it means some imap clients wont work well. For details visit the Courier-imap website .

Known bugs

None yet.

The final word

Im tired, and wonder if anyone will ever use this, but I'm happy its done. I'm sure if you have read this far your tired too. Well, all I can hope is that you have Qmail, VMailMgr and Courier-imap working. If so, Enjoy! If not, bummer!

O.K. readers, you're done for today. Feel free to send me your feedback, eternal gratitude, flowers, ecash, cars, oil sources etc.