You know how it is. Your little mail host has just sat there for a long while, slowly accreting a user here and a user there. They are all full users on the machine, so they have logins and everything, and exim is configured to deliver their mails to ~/Maildir.
And then some dangerous loon suddenly demands that you add mailboxes for people using a completely different domain. They're not really much to do with you, and certainly shouldn't be full-blown users on your host.
Time, then, to add virtual mailboxes to your poor little mail host.
There all sorts of HOWTOs on doing this, of various ages and usefulness. I'm adding this page to the malestrom just to document the configuration changes I did. Or rather, the configuration changes I ended up with. The details of configuration aren't original, but synthesised from too many of the HOWTOs I read to properly credit each.
I'm illustrating this by setting up a new domain example.mod with user tommy.atkins.
First I created a user and group vmail to own all virtual mailboxes. I make the user a normal user because Dovecot will try to access all virtual mailboxes as that vmail user, and in Dovecot 2.x on Debian the config first_valid_uid is set to 500 to prevent attempts to access daemon mailboxes.
# adduser --home /var/local/vmail --group vmail
and a configuration directory.
# mkdir /etc/vmail
Configuration information for the domain will be under /etc/vmail/<domain>. If that directory doesn't exist, the domain isn't supported.
# mkdir /etc/vmail/example.mod
The general scheme is that we have mailboxes under /var/local/vmail/<domain>/<user>/Maildir. Why Maildir? Because our existing users will continue to get mail in ~/Maildir and it keeps dovecot config a little simpler.
# mkdir -p /var/local/vmail/example.mod # chown -R vmail:vmail /var/local/vmail
Now add two configuration files. The first, aliases, is a conventional aliases file for the domain.
# cat > /etc/vmail/example.mod/aliases postmaster: root webmaster: root security: root admin: root root: guru@example-owner.mod squaddie: tommy.atkins ^D
The second, passwd contains the account information for the domain. There are two items on a line, username and password hash, separated by a colon. Generate the password has using the dovecotadm pw utility. Just to be on the safe side, we'll ensure the password file isn't world readable and is readable by Dovecot and Exim.
# doveadm pw -s SHA256-CRYPT -p password
{SHA256-CRYPT}$5$TQGxffy9XCxe53vu$L2NWgKJ47w3PoAIj3/IxLJIREA9QSyBKdKDMJlXvn07
# cat > /etc/vmail/example.mod/passwd
tommy.atkins:{SHA256-CRYPT}$5$TQGxffy9XCxe53vu$L2NWgKJ47w3PoAIj3/IxLJIREA9QSyBKdKDMJlXvn07
^D
# chown dovecot:vmail /etc/vmail/example.mod/passwd
# adduser Debian-exim vmail
# chmod 0660 /etc/vmail/example.mod/passwd
The next step is to configure Exim to deliver to virtual mailboxes.
Exactly how you do this depends on which of Debian's configuration schemes you are using. I am using the conf.d multiple configuration file hierarchy with the config type internet. From here on, I'll show what I ended up with in the Exim configuration file, and indicate where I put each entry in the conf.d hierarchy. Please treat these as an illustration; if you have a setup reasonably close to the standard installed version then I think these will probably work for you, but I can't promise.
The first thing to do is to add the domain to the list of local domains. You need to end up with a configuration file with the domain as part of the domainlist local_domains. I wanted to have the virtual mail domains work automatically, rather than have to add them manually to the list of local domains. I first added a configuration main/00_vmail_config with some definitions:
VMAIL_DELIVERY=dovecot_vmail VMAIL_DOMAINS=dsearch;/etc/vmail VMAIL_ALIASES=/etc/vmail/$domain/aliases VMAIL_PASSWD=/etc/vmail/$domain/passwd VMAIL_MAILBOX_DIR=/var/local/vmail/$domain
That dsearch;/etc/vmail will expand to a list of the files/directories under /etc/vmail. Which will be the domains to be handled.
I then made a small modification to main/01_exim4-config_listmacrosdefs to add the virtual mail domains to the list of local domains:
# Local modification - add vmail domains to local domains, and provide # main_local_domains for the non-vmail domains. domainlist local_domains = MAIN_LOCAL_DOMAINS : VMAIL_DOMAINS domainlist main_local_domains = MAIN_LOCAL_DOMAINS
(I use main_local_domains elsewhere in my processing of non-virtual mail domains.)
Next I need a router to expand virtual domain aliases. I put this into router/170_vmail_aliases.
vmail_aliases:
driver = redirect
domains = VMAIL_DOMAINS
allow_fail
allow_defer
data = ${lookup{$local_part}lsearch{VMAIL_ALIASES}}
qualify_domain = $domain
qualify_domain = $domain ensures the expanded alias, if any, has the same domain as the original, if the domain is not specified in the alias.
Once that's done, I can think about routing virtual mail users to a transport for delivery, and rejecting messages to unknown users in a virtual mail domain. I put this into router/180_vmail_user.
vmail_user: driver = accept domains = VMAIL_DOMAINS local_parts = lsearch;VMAIL_PASSWD transport = VMAIL_DELIVERY vmail_no_such_user: driver = redirect domains = VMAIL_DOMAINS allow_fail = true data = :fail: Unknown user more = false
Here I'm accepting the mail on condition that the local part of the address appears in the domain's password file. If it does, the message proceeds to the virtual mail delivery transport. Otherwise, the user does not exist in the virtual mail domain and I can fail delivery and give up.
Now to the transports. I am now delivering all mail using Dovecot deliver. I define a transport for this in transport/30_dovecot_vmail and select it using the VMAIL_DELIVERY definition.
dovecot_vmail: driver = pipe command = /usr/lib/dovecot/deliver -d $local_part@$domain -f $sender_address -a $original_local_part@$original_domain message_prefix = message_suffix = log_output delivery_date_add envelope_to_add return_path_add user = vmail temp_errors = 64 : 69 : 70: 71 : 72 : 73 : 74 : 75 : 78
Prior to using Dovecot deliver, I had Exim deliver virtual mail itself, with this transport in transport/30_vmail_home.
vmail_home: driver = appendfile envelope_to_add directory = VMAIL_MAILBOX_DIR/$local_part/Maildir maildir_format create_directory = true user = vmail group = vmail return_path_add
This transport adds the message to the user's Maildir. It runs as user and group vmail and will create any directories that don't exist.
By the way, when you add a user, it's an idea to either send them a welcome mail to check things are working properly and create their Maildir into the bargain. Otherwise, you should create the Maildir by hand, so that there is something there when they try to read their mail.
When that's done, test your handiwork:
# exim4 -bt tommy.atkins@example.mod tommy.atkins@example.mod router = vmail_user, transport = dovecot_vmail
Now we need to modify the Dovecot setup to allow our user to read mail.
I'm assuming your dovecot.conf already has
mail_location = maildir:~/Maildir
in it, telling Dovecot to find your regular users mail in ~/Maildir.
We need to add the virtual domains to the
auth default {
}
section of the configuration. The first stage is to add the virtual users password files.
passdb passwd-file {
args = username_format=%n /etc/vmail/%d/passwd
}
Here's a tip. My configuration also has a configuration for PAM
passdb pam {
}
Put the virtual users passwd-file entry before the pam section. If you don't, your virtual usernames will be tried in pam first. Confusion will abound if they succeed. And if they don't, it will look to programs like denyhosts or fail2ban as if a PAM login failed, and you may find access to the host unexpectedly blocked.
Now you need to add a userdb section telling Dovecot how to find the mailbox. You will have a
userdb passwd {
}
section serving your existing users. After that, add a catch-all for the virtual mailbox users.
userdb static {
args = uid=vmail gid=vmail home=/var/local/vmail/%d/%n
}
This tells Dovecot to use vmail permissions to access the mailbox, and that the user home is at /var/local/main/<domain>/<user>. Dovecot will apply it's existing rule that the mail is to be found in directory Maildir under the user's home, and you are off to the races.
In practice, you'll most probably run into authentication problems. For help sorting them out, add
auth_debug = yes auth_debug_passwords = yes
to your dovecot.conf while you try and work out what's going wrong.
Again, I'm assuming that 10-mail.conf has
mail_location = maildir:~/Maildir
in it, telling Dovecot to find your regular users mail in ~/Maildir.
I first added a new auth configuration file, auth-vmail.conf.ext.
# Virtual mailbox passwords.
passdb {
driver = passwd-file
args = username_format=%n /etc/vmail/%d/passwd
}
# VMail static settings.
userdb {
driver = static
args = uid=vmail gid=vmail home=/var/local/vmail/%d/%n
}
This gives Dovecot the essential password and user info settings.
I then modified 10-auth.conf, adding the new vmail auth at the end of the file.
!include auth-vmail.conf.ext
To debug authentication problems, enable auth_debug and auth_debug_passwords in 10-logging.conf.
Your virtual mail users will probably want to send some mail, too. So you may want to give them access to your Exim server to relay mail. But, of course, you don't want world+dog also relaying their spam through your host.
There's several ways of cracking this nut. I'll just mention that if you do it by allowing authenticated SMTP, I found it easiest to do by handing the authentication over to Dovecot.
I needed to create the Dovecot authenticator socket by adding
socket listen {
client {
path = /var/run/dovecot/auth-client
mode = 0666
}
}
to the
auth default {
}
section in dovecot.conf. It's commented out by default in Debian. Without other arrangements, Exim needs its mode to be 0666; comments in the Dovecot config suggest this is generally safe.
Then, in the Exim configuration, add auth/30_dovecot_auth containing:
dovecot_plain: driver = dovecot public_name = PLAIN server_socket = /var/run/dovecot/auth-client #server_set_id = $auth2 server_mail_auth_condition = false dovecot_login: driver = dovecot public_name = LOGIN server_socket = /var/run/dovecot/auth-client #server_set_id = $auth2 server_mail_auth_condition = false
In 10-master.conf I add a Dovecot authenticator socket with permissions for Exim by adding the following lines in the section service auth.
unix_listener auth-client {
mode = 0660
group = Debian-exim
}
Then add auth/30_dovecot_auth to the Exim configuration as above.