Virtual mailboxes with courier-imap and postfix
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
firstname.lastname@example.org 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
email@example.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.
/etc/postfix/main.cf add the following lines:
virtual_alias_domains = dannorth.net virtual_alias_maps = hash:/etc/postfix/virtual
This says that postfix will treat the name
dannorth.net 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 firstname.lastname@example.org dan # forward to another mail address email@example.com firstname.lastname@example.org
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 ¶
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
email@example.com example.com/fred/ firstname.lastname@example.org 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-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:
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:
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
/etc/courier/authdaemonrc and restarting the auth daemon. Don’t forget to switch it off again once it’s working.