In the past couple of hours I’ve managed to fix 3 different screwups I made with qmail. Because having to deal with qmail (or rather, MTAs in general) always gets me upset, I figured I’d document what I’ve done for posterity. Sorry to the Planet KDE readers, this is longer than I thought it would be.

For starters, when you setup qmail, don’t forget to add all the aliases for your machine to the /var/qmail/control/locals file. No, qmail doesn’t know that localhost is actually a local machine, nor does it automatically know about your computer name. So in my case, I’d forgot to add midna (the computer name) and localhost to the locals file before email was being sent, and although qmail retained it, it was trapped in the queue, unable to be delivered.

qmail splits up its queue into two sections, remote (which it tries to deliver over SMTP) and local (which it normally can just deliver to on disk). In my case qmail is pretty much receive-only, so SMTP-outbound delivery wasn’t working (and wasn’t likely to1). And anyways, all the crap stuck in the remote queue really belongs in the local queue, and it would have been there if I hadn’t screwed up the locals file.

Now the QMail queue is a very touchy part of the filesystem. Try moving files around and you’ll likely hose all the email retained in there, not to mention any email delivered to qmail in the future. So it’s not like you can just move messages from the remote to the local queue. Instead, what you should to when you’ve got messages in the remote queue that need delivered locally, is to play with the /var/qmail/control/smtproutes file. This file controls the SMTP servers which are used to relay messages.

Something like this will tell QMail that messages intended for your local domain should be SMTP’ed out to localhost. QMail will receive them and, since your locals file is now correct will put them in the local queue where they’ll be delivered.


That takes care of the first problem. But, don’t forget to remove the entry again after the mail has been placed in the local queue! Another problem I was having was that emails to an old user of mine weren’t being delivered to the correct email account. qmail has nifty support for address of the type user-foo@domain, where the -foo part can be whatever user wants, which is nice for getting unique email address to give to merchants or other websites you suspect may give away your address. It’s even useful simply for filtering (which is what I was using this particular address for).

Now qmail also has a nifty aliasing feature that allows messages sent to a virtual user to be redirected to a mailbox. All you do is create a .qmail-user file in /var/qmail/alias, the contents of which is the name of the mailbox to send to (i.e. mpyne).

But, this has two problems. First, email sent to user-foo won’t be redirected. If you want that to happen you need to name the alias file .qmail-user-foo. This would get unwieldy (imagine all the possible suffixes you could have added). But, if you have a .qmail-user-default alias, then any email which doesn’t match a different alias for the user will be redirected to that alias. So that solved my second problem.

The final problem is that the alias feature doesn’t work if you’re trying to alias email for a user that has an account on the system. In my case, I was having email sent to portage@midna forwarded to my account. But, portage is an actual user account on Gentoo systems. So even though the alias existed, qmail was searching for portage in /etc/passwd first, and found the entry. qmail in this situation then checks to see if the user owns their home directory, that the permissions are set right, etc. That wasn’t true in this case, so email sent to portage was in limbo.

The solution here is to take advantage of a QMail users database. By default in /var/qmail/users. You need to read the man page for qmail-users, but basically you setup the file /var/qmail/users/assign to redirect email for the user to someone else, run the qmail-newu program, and then the user database which is created is checked first, before checking for the home directory. And if the user isn’t present in the database then the rest of the sequence goes on unchanged so this won’t break your aliases and existing mailboxes2.

My disclaimer is that this is all probably completely different if you’re using software like vpopmail or other user administration software bolted on top of qmail. My particular scenario was a qmail-only install. You may want to have the qmHandle program or similar available to help manage messages in your queue. And, be vary wary with any queue changes while qmail is still running. pkill -HUP qmail-send is your friend when changing files in /var/qmail/control. Sometimes restarting qmail is in order as well.