Virtual mailboxes with courier-imap and postfix

6 mins
, , , , , ,

This is the first of an occasional series of posts about Linux systems administration. I’ve been an on-off Linux sysadmin for about, well, my first Linux was Slackware on a stack of 3.5" floppies. Every now and then I do something “fiddly” and I want to capture these episodes in case I ever need to do it again, or in case someone else wants to and they find this useful.

I run Debian Testing on kenny, the server that hosts http://jbehave.org, http://behaviour-driven.org and a bunch of other websites, blogs and wikis. (Random plug: it’s hosted by the fine folks at SolarVPS. I have no affiliation with them but they rock.) It seems a good balance between Debian Stable—which is rock solid but always about a year out of date—and Unstable, which requires updating far too often and hosed my old server (cartman - can you see a theme here?).

Mostly it Just Works. In particular WordPress and MoinMoin are a joy to configure and use. I get change out of about 10 minutes to add a new blog.

I also use it as a mail server, using postfix for sending and receiving mail and courier-imap for reading it. I tried a number of mail servers and settled on postfix after dismissing sendmail and qmail as just too complicated and exim after staring at the impenetrable documentation one time too many.

I found it pretty easy to set up secure SMTP over TLS and secure IMAP over SSL, but I stumbled at setting up virtual mail addresses. This article is about how to do that using postfix and courier-imap. It’s pretty straightforward once you know where all the moving parts are, but they were less than obvious to me.

Virtual mail addresses

Mostly you send email to bob@address.com and it turns up in bob’s mailbox in bob’s login account. Sometimes you don’t want this. For instance, I host about 20 domain names on kenny, and addresses like info@blah.com or sales@blah.com need to go to specific people. That’s the first type of virtual addressing, known as virtual alias domains.

The second case is “more” virtual - the user doesn’t even need to exist on the server with a regular login account. Postfix puts the mail into a special directory, and courier-imap presents that directory as the mailbox when the user “logs in” over IMAP. This is where all the moving parts come in. This is known as virtual mailbox domains.

Setting up postfix for virtual alias domains

This is the easier of the two, since the mail ends up in a real email address, so there is no corresponding configuration on the courier-imap side. This information came from the Postfix Virtual Domain Hosting Howto.

In /etc/postfix/main.cf add the following lines:

 virtual_alias_domains = example.com
 virtual_alias_maps = hash:/etc/postfix/virtual

This says that postfix will treat the name example.com as a virtual alias domain and will use the file /etc/postfix/virtual to do the mappings. Your /etc/postfix/virtual might look like this:

 # deliver to local account
 bob@example.com bob

 # forward to another mail address
 alias@example.com bob@example.com

Once you have this file configured, run the command:

 # postmap /etc/postfix/virtual

to create the hash database that postfix will use, then run:

 # postfix reload

to update the configuration.

Setting up virtual mailbox domains

Ok, there are several moving parts here. We need:

  • a directory to deliver the mail to
  • to tell postfix to deliver it there
  • to enable virtual users in courier
  • to tell courier where the virtual users’ mail lives

In this example, I’ll set up two virtual users, fred and barney, at example.com.

System accounts and directories

The virtual users’ files need to be owned by someone, so we’ll create a “fake” user and group. I’m using vmail for both the user and group names, with uid and gid both set to 5000.

From a root prompt:

 # groupadd -g 5000 vmail
 # useradd -g vmail -u 5000 vmail
 # mkdir -p /home/vhosts/example.com
 # chown vmail:vmail /home/vhosts/example.com

Configuring postfix for virtual mailbox domains

In /etc/postfix/main.cf

 virtual_mailbox_domains = example.com
 virtual_mailbox_base = /home/vhosts
 virtual_mailbox_maps = hash:/etc/postfix/vmailbox
 virtual_minimum_uid = 100
 virtual_uid_maps = static:5000
 virtual_gid_maps = static:5000

This is pretty self-explanatory. It says example.com is a magic virtual mailbox domain, all users and groups map to a fixed number (you can get cleverer than this but I’m not worried about it for now), and that all the interesting stuff is in /etc/postfix/vmailbox. The minimum uid is postfix’s safety measure in case I do something stupid. It means I can’t accidentally let someone have access to system files.

Now let’s look at /etc/postfix/vmailbox:

 fred@example.com example.com/fred/
 barney@example.com example.com/barney/

The magic here is the / at the end of each line. This says to use maildir format (the format courier-imap is expecting) rather than clunky old mbox format. Postfix will create the appropriate directory structure for fred and barney,

Again we create a hash of this for postfix:

 # postmap /etc/postfix/vmailbox
 # postfix reload

Phew! That’s the postfix side done. Now stop for a cup of tea.

Configuring courier-imap for virtual mailboxes

On Debian, courier imap runs as three executables, each with separate init.d scripts. courier-imap and courier-imap-ssl are the imap servers themselves (I run courier-imap bound to localhost for webmail). courier-authdaemon is the chap that does all the authentication. That’s the one we’re interested in.

Firstly, we need to enable virtual users. In the file /etc/courier/authdaemonrc you need to make sure your authmodulelist setting contains authuserdb as one of its authentication mechanisms. Mine looks like this:

 authmodulelist="authuserdb authpam"

Don’t forget to tell the auth daemon you’ve made a change:

 # invoke-rc.d courier-authdaemon reload

Courier uses a file called /etc/courier/userdb to store virtual user mappings, but you don’t usually edit this file yourself. It has an arcane format (using tabs and pipes as delimiters) and should be left well alone. Instead, courier provides you with some command line tools to manipulate it.

To create an entry for fred, we do this:

 # userdb fred set uid=vmail gid=vmail home=/home/vhosts/example.com/fred mail=/home/vhosts/example.com/fred

(That should all be on one line - your browser might wrap it.) Then set a password for fred:

 # userdbpw -md5 | userdb fred set systempw

Do the same for barney. Finally we build the hashed user database that courier will actually use:

 # makeuserdb

Note: don’t forget to run makeuserdb after making any changes to the virtual user data otherwise courier won’t know.

Testing the configuration

Firstly, try sending an email to the virtual user. Postfix should create the maildir structure under example.com/fred. Then try connecting to courier to read the mail. If you find you are getting authentication problems from the courier side, you can try setting DEBUG_LOGIN=1 in /etc/courier/authdaemonrc and restarting the auth daemon. Don’t forget to switch it off again once it’s working.