Qmail, Mail toaster

THIS IS A WORK IN PROGRESS. It will be moved to an alternate location when complete. Please do not attempt to edit it yet. Thanks! --Jimbo 13:40, 14 Dec 2004 (EST)

First things first - synchronize your ports tree to make sure you get the newest versions of all the ports you'll be installing. Mailserver components are critical, you don't want to wind up with something outdated that could potentially have had a vulnerability disclosed in it!

ph34r# cvsup /usr/share/examples/cvsup/ports-supfile

Now, it's time to get the basics installed - first things first, get Qmail installed with the SMTP_AUTH and the TLS patches in place. This will allow us not only to send and receive mail, but also to authenticate SMTP sessions with a username and password so that authorized "road warriors" can use this server to send their email no matter what network they are physically attached to, and to use TLS encryption if supported on the remote end (which might be one of those road warriors, or might be another domain's mailserver) to keep potential unfriendlies from easily sniffing potentially sensitive information out of our email.

Note that we're NOT issuing make install clean as a single command here, because there are other steps we want to take after building the port before we clean out the work directory!

ph34r# cd /usr/ports/mail/qmail-smtp_auth+tls
ph34r# make enable-qmail

Now we'll need to install a certificate for use with TLS authentication/encryption. To make a certificate request, you can type in make certificate-req - but that's all I can tell you about that process; I typically use a self-signed certificate instead (one which is not stored at Thawte or Verisign or one of the other major providers, but only on the local server). You don't have to pay for a self-signed certificate, where you would for one from Thawte or Verisign et al, but you should be aware that 1. users will be warned that they are being asked to accept a certificate not signed by a recognized authority the first time they connect to a server with a self-signed certificate, and 2. Microsoft Outlook may refuse to connect to a server with a self-signed certificate using TLS AT ALL, so you may need to forgo encryption entirely for Outlook users if you're signing your own certificate.

Whew! With that said, actually generating the certificate is easy:

ph34r# make certificate

After entering in a bit of info at some prompts - country, state, city, that sort of thing - a certificate will be created and saved in /var/qmail/control/servercert.pem. All done. One thing worth noting - whatever you enter at the prompt that says Common Name (eg, YOUR name) []: is what's going to show up in security prompts in browsers and email clients, and frequently will trigger EXTRA "oh no something's not right!" prompting if it doesn't match the URL of your server. So in general, if you were creating this certificate for a mailserver mail.getsdeliveredhere.net, you would want to enter mail.getsdeliveredhere.net at that prompt.

Now it's time to make sure Qmail knows how to deliver the mail it receives. The way we do this is by selecting one of a large selection of possible startup scripts from /var/qmail/boot, and copying that script to /var/qmail/rc, which is symlinked to /usr/local/etc/rc.d/qmail.sh for starting and stopping Qmail when needed. We're going to be using the maildir storage format, so this is the command we'll issue:

ph34r# cp /var/qmail/boot/maildir /var/qmail/rc

Easy enough. Now it's time to make sure that we can keep our mail accounts separate from our system accounts - maybe you want every Tom, Dick, and Harry with an email account to potentially be able to use that username and password to get a shell prompt, but I certainly don't! In fact, even for those folks - like myself - who have both a mailbox and a shell account, I want to make certain that the credentials used AREN'T the same, to minimize security risks. I also want to make it easy to administer the email for multiple domains from a single machine - and that's where vpopmail comes in.

ph34r# cd /usr/ports/mail/vpopmail
ph34r# make install clean

Mmmmm, simple. As a bonus, that also gets us the ucspi-tcp port, which we'll need to use to keep a daemon listening on port 25 (and port 2525, for reasons we'll discuss later) for incoming SMTP traffic. Okay, but now that we've got a separate database for mailbox accounts from system accounts, how do we manage it? That would be two more ports - qmailadmin, and vqadmin. Vqadmin lets us add, delete, and otherwise manage entire domains we want to handle the mail for, while qmailadmin gives us a nice friendly little interface to handle individual mailboxes within individual domains. First, vqadmin:

ph34r# cd /usr/ports/mail/vqadmin
ph34r# make install clean

Now, vqadmin just put files in /usr/local/www/cgi-bin-dist/vqadmin. This is probably NOT where you actually want those files to go - so you'll want to move that whole directory to wherever you actually want it served from. For the purposes of this article, we'll assume that it's a mailserver and a mailserver only, and so you're just serving everything from /usr/local/www/data and /usr/local/www/cgi-bin. So mv /usr/local/www/cgi-bin-dist/vqadmin /usr/local/www/cgi-bin and we can move on.

Now we'll need to add a snippet to our httpd.conf file to handle authentication for us when we use vqadmin:

# VQadmin : web interface for administering Qmail

<Directory "/usr/local/www/cgi-bin/vqadmin">
        deny from all
        Options ExecCGI
        AllowOverride AuthConfig
        Order deny,allow
</Directory>

All that does is make sure that access is allowed to our vqadmin directory, but ONLY allowed for authorized users. Next, we'll need to create a .htaccess file and a password file to tell the system what does or does not constitute an authorized user. First, create the .htaccess file in the directory you put vqadmin in (in this example /usr/local/www/cgi-bin/vqadmin):

# This is /usr/local/www/cgi-bin/vqadmin/.htaccess

AuthType Basic
AuthUserFile /usr/local/www/vqadmin.passwd
AuthName vQadmin
require valid-user
satisfy any

Now, it's time to create the password file referenced in the .htaccess file you just wrote. In this example, we're going to use the username "admin" because it's already configured in vqadmin's vqadmin.acl file to be an administrator account when present - REMEMBER, if instead you choose to use a different username, and you want that username to be able to administer vqadmin as well as look at it, you'll need to edit vqadmin.acl as well to reflect that!

ph34r# htpasswd -c /usr/local/www/vqadmin.passwd admin
New password:
Re-type new password:
Adding password for user admin

The htpasswd command, with the -c flag, will create the new file and will add the user "admin", with the password you specify twice on the command line when prompted. The screen will not echo your keystrokes or any asterisks; it will just sit there until you hit enter at each password prompt.

Okay! Now you should be ready to add your first (possibly your only) domain, using vqadmin. First, restart Apache so that the changes you made to httpd.conf will take effect:

ph34r# apachectl restart

Now fire up your web browser and check out your particular version of "www.yourdomainname.tld/cgi-bin/vqadmin/vqadmin.cgi". You should get a plain-but-functional HTML page showing you links to add/delete/otherwise maintain your domains. Add a domain here, and let's move on to qmailadmin.