Qmail, Mail toaster

From FreeBSDwiki
Revision as of 23:27, 18 December 2008 by (Talk)
Jump to: navigation, search


What is a mail toaster, and what are we doing here?

A "mail toaster" is a silly name for a very useful and commonly needed "applicance" - a single server that can handle everything you need to do with email: receive it, send it, weed out spam, allow webmail access, allow authenticated SMTP traffic so that laptop users and other "road warriors" can send email from any network they happen to be attached to, handle multiple mail domains, allow delegation of web-based administration of individual domains to individuals responsible for those domains (and their domain only), and even allow delegation of web-based individual mailbox maintenance to owners of the individual mailboxes.

When you're done following through this article, you'll have a machine which will do exactly that - and even a few things more, like allow users to set "auto-reply" messages, forward their mail temporarily to other addresses, you name it.

(If you have a Microsoft Active Directory setup for your users, you may want to look at using qmail-ldap instead. But that's an entirely different animal.)

We'll be using the following ports:

  • apache2
  • qmail-tls
  • ucspi-tcp
  • vpopmail
  • vqadmin
  • qmailadmin
  • sqwebmail
  • dovecot
  • qsheff
  • safecat
  • clamav
  • p5-Mail-SpamAssassin


First of all, you're going to need a FreeBSD server - all of the applications we're going to use are free software and available for pretty much any *nix, but we're going to be covering installing them using the ports tree... so your mileage would vary considerably were you to be trying to follow this article along on a Linux or Solaris or what have you.

Second of all, you're going to need DNS information set up to point the mail services (MX records) for any domains that you want to handle mail for at this machine. You may or may not want the same server to act as nameserver (DNS server) and mailserver, but either way, setting up DNS is beyond the scope of this article... we're just going to set up the services themselves here, not set up the internet to point the mail at us to begin with.

Finally, before we get started, be sure to 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

And now that we have the latest versions of all of our ports, let's get started!

Installing Apache2

This is probably the easiest part of the whole process. Note: if you've already got your own copy of Apache up and running and you know how to care for it and feed it, that's perfectly fine, and you can skip on ahead to the next section - we aren't really going to do a whole lot of magical things with the webserver, we just need it available so that we can deliver our webmail and web-based control interfaces. It's also fine if you're using Apache 1.x instead of Apache 2.x; just make your own little adjustments and follow right along.

ph34r# cd /usr/ports/www/apache2
ph34r# make install clean

When the port's done building, rehash to update your system's PATH cache, and start Apache:

ph34r# rehash
ph34r# apachectl start

Check to make sure it's running:

ph34r# ps ax | grep httpd
91237  ??  Ss     0:00.37 /usr/local/sbin/httpd -k start
91246  ??  S      0:00.00 /usr/local/sbin/httpd -k start
91247  ??  S      0:00.00 /usr/local/sbin/httpd -k start
91248  ??  S      0:00.00 /usr/local/sbin/httpd -k start
91249  ??  S      0:00.00 /usr/local/sbin/httpd -k start
91250  ??  S      0:00.00 /usr/local/sbin/httpd -k start

And we're good! Now, on to the parts that actually handle the mail...

Installing Qmail with SMTP Authentication

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-tls
ph34r# make config

You'll get an NCURSES text-mode gui config screen now, and you want to make sure to check the SMTP_AUTH_PATCH and RCDLINK options before you go on. You may also want DISCBOUNCES, MAILDIRQUOTA, and LOCALTIME, at your discretion. Once that's done, we'll grab all our files and apply the FreeBSD port's patches before applying our own:

ph34r# make fetch
ph34r# make patch

Now we want to apply a couple of custom patches of our own - one to allow issuing custom SMTP 554 errors, and one to tell Qmail NOT to tell mail clients it allows CRAM-MD5 logins for authenticated SMTP (since Vpopmail's vchkpw password check program doesn't support it, so you wind up failing the first AUTH check and falling back on PLAIN every time you try to send an email otherwise).

ph34r# cd work/qmail-1.03
ph34r# fetch
ph34r# patch < Qqxrc.patch.txt

Pay careful attention to the output of the patch program: if it tells you any hunks failed, you'll need to investigate and resolve the problem or who knows what you'll wind up with. Next, we want to make sure Qmail doesn't tell mail clients that we accept CRAM-MD5 logins, since Qmail would take them but vchkpw would fail to understand them. You can use this patch if you like, but I'd recommend just using this quick-and-dirty "poor man's patch" instead:

ph34r# sed -i .bak s/CRAM-MD5\ // qmail-smtpd.c

Now we can change back into our port directory and issue a make install.

ph34r# 'cd ../..
ph34r# make install

Making or Requesting a Certificate for Qmail's TLS

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.

To use a certificate from a known-and-trusted certifying authority (Thawte/Verisign etc,) you'll need to create a CSR and send it to them when you ask them for a certificate. Be prepared to pay ~200USD for a cert. They'll send you the certificate back and you'll need to install it on your server. This is made easier by webmin, but you can do it via the commandline using OpenSSL. Certificate management is outside the scope of this article and not something to be taken lightly, as it can be more subtle and difficult than it initially appears.

Whew! With that said, actually generating the self-signed 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, you would want to enter at that prompt.

Initial Qmail Configuration

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/ 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

Now add a line to /etc/rc.conf so that the startup script we just copied will run automatically when we boot the machine up:

ph34r# echo SENDMAIL_ENABLE="NONE" >> /etc/rc.conf

Now we'll need to generate Qmail's basic control files. Easy:

ph34r# /var/qmail/configure/config-fast
Your fully qualified host name is .
Putting  into control/me...
Putting  into control/defaultdomain...
Putting  into control/plusdomain...
Putting  into control/locals...
Putting  into control/rcpthosts...
Now qmail will refuse to accept SMTP messages except to .
Make sure to change rcpthosts if you add hosts to locals or virtualdomains!

Now you need to put the real name of the machine in /var/qmail/control/me - nothing fancy here, no comments, no arguments to set, just edit the file and put the name of the server in there; ie Don't worry about locals, rcpthosts, or any of that good stuff - vpopmail will handle that for us, and we're going to cover that next. But first, we need to fire up qmail and make sure it's running:

ph34r# /usr/local/etc/rc.d/ start
ph34r# ps ax | grep qmail
87877  p0  R      0:00.26 qmail-send
87878  p0  S      0:00.10 splogger qmail
87879  p0  S      0:00.00 qmail-lspawn ./Maildir/
87880  p0  S      0:00.03 qmail-rspawn
87881  p0  S      0:00.03 qmail-clean

Good deal! Now let's move on to vpopmail.

Installing vpopmail

Now, we want 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

Now we need to make a quick permissions change, so that our authenticated SMTP will work right with Vpopmail's password authentication program:

ph34r# chmod 4755 /usr/local/vpopmail/bin/vchkpw
ph34r# chown root /usr/local/vpopmail/bin/vchkpw

Mmmmm, simple. That's all we have to do with vpopmail. As a bonus, installing vpopmail also got 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. Vqe MUCH easier.

Now let's test POP3 (assuming you want to allow clients to use POP3 as well):

ph34r# telnet localhost 110
Connected to localhost.localdomain.
Escape character is '^]'.
+OK dovecot ready.
PASS thisismypassword
+OK Logged in.
+OK 1 messages:
1 354
+OK Logging out.
Connection closed by foreign host.

Tested, confirmed, and good to go!

Configuring Email Clients

Well, we're all done now - we've got a fully functioning mailserver that can handle sending and receiving mail, authenticated SMTP (with and without TLS encryption), webmail, virtual domains, delegation of administration by domain and by individual mailbox, IMAP storage, POP3 for people who can't use IMAP, spam filtering by RBL, and more. Once you've set up your domains and your user accounts (and don't forget for every domain you set up, you will also need DNS pointing the mail services for that domain to this server, which isn't covered in this article), the only thing left is configuring your clients. Here's a few basic bullets to help you with common SNAFUs with that:

  • remember to set the "username" as mailbox@domainname.tld, not just "mailbox"
  • remember that in order to send email, the client either has to be on the network named in /etc/tcp.smtp (actually in the compiled version, /etc/tcp.smtp.cdb) or has to login using Authenticated SMTP
  • remember that if you expect the client machine to be able to connect reliably from foreign networks, you should configure it to connect to your SMTP server on a nonstandard port
  • remember that if you're using a self-signed certificate, you will get security warnings from some clients if you use TLS encryption, and some other clients (notably Microsoft Outlook) will refuse to connect at all using TLS encryption if your certificate is self-signed

And that's pretty much it - enjoy!

See also

Personal tools