Generic Virtualization Framework

The most straightforward mail handling in qmail is used for what are known as the local domains: those listed in the file. The users for these domains are all the same, and are typically the users defined in control/locals/etc/passwd, though they can be defined in users/assign as well (discussed in the Non-Virtual Non-System Users section). Qmail, however, has another sense in which an email can be local, which is to assign a domain to a user (or, more accurately, to a prefix). This feature is configured with the control/virtualdomains file.

Power of the virtualdomains File

The virtualdomains file is one of the most powerful, useful, and stunningly simple mechanisms for configuring qmail. Virtual domains and even virtual users can be created, independently of one another, and assigned to controlling users. Virtual domains are fully independent, and as they are assigned to users (or, more accurately, prefixes) they can be in different UNIX protection domains if desired. This file can also define virtual users and similarly assign them to controlling users. This file thus makes it both possible and easy to intercept specific addresses and do something special with them.

Perhaps surprisingly for the power this file wields, the control/virtualdomains file is only slightly more complicated than similar control files, such as control/locals. Rather than a list of domains, the virtualdomains file is a list of patterns and their associated prefixes. The entries are of the form:

matching-pattern: prefix

Only one prefix is associated with each pattern. The matching pattern can be one of the following three things: a domain (that follows the same wildcarding semantics used in the control/rcpthosts file), an email address, or an empty string. The empty string is considered to match anything. An email address matches any message addressed to that email address, and a domain matches any message addressed to a user in that domain. If there are multiple possible matches, the longest match is used.

Emails that match patterns listed in the control/virtualdomains file are considered to be local emails, similar to those addressed to domains in the control/locals file. Messages that match patterns in the virtualdomains file must first undergo a simple modification before delivery. While messages are prepared for delivery, if they have an envelope destination address that matches a pattern in the virtualdomains file, that destination address is prepended with the matching pattern’s associated prefix. This turns the original local part of the address into an extension of the prepended user. In this way, a domain can be mapped to a user, giving that user full control over the mailboxes (or users) within that domain. The virtualdomains file can also be used to define exceptions to the matching rules, if the prefix is blank.

It is important to note that the control/virtualdomains file is considered after the control/locals file, which means that if an email is addressed to a domain listed in locals, the virtualdomains file will not apply. Also, virtualdomains rewriting occurs before the mail is given to qmail-lspawn for delivery. This sounds complex, but is easy to understand with an example.

Basic Virtual Domains

An example virtualdomains file that demonstrates most of the file’s features is as follows:

example.com:foo
.example.com:foo-bar
two.example.com:baz
waldo@domain.com:qux
domain.com:
:garply

Presuming that the users mentioned i.e. foo, baz, qux, and garply are the only local users on this system; these lines cause the following results:

1. The first line matches any address ending in @example.com, such as user@example.com. Such a destination address will be rewritten as foo-user@example.com, ensuring that the email’s delivery will be controlled by the local user named foo.

    

2. Messages addressed to user@something.example.com do not match the first line but do match the second line, and so will be delivered as if they had been addressed to foo-bar-user@something.example.com.

    

3. Because the virtualdomains file is used in a longest match wins manner, the third line (not the second) will match messages addressed to user@two.example.com. This destination will be rewritten asbaz-user@two.example.com and baz will control the delivery of such messages.

    

4. The fourth line specifies that email addressed to waldo@domain.com will be instead delivered as if it had been addressed to qux-waldo@domain.com. The qux user will control that delivery.

    

5. The fifth line specifies that any domain.com email—other than waldo@domain.com—should be treated as if had been listed in the domain.comcontrol/locals file.

    

6. Finally, the sixth line specifies that all other email will be rewritten and delivered to the local garply user. For example, email addressed to someone@somewhere.org will be rewritten as garply-someone@somewhere.org and delivery will be attempted locally.

In this example, the foo user is essentially in charge of the entirety of the example.com domains. Users that are specific to example.com are defined by creating appropriately named .qmail files in foo’s home directory.

For example, to establish the standard postmaster@example.com address, foo would create a file named .qmail-postmaster in its home directory, containing the instructions for delivering postmaster’s email. The foo user could also establish a address by creating a file named foo@example.com.qmail-foo in his or her home directory. In this way, once the example.com mapping has been established, the foo user can set up and maintain the users in the example.com domain without ever requiring further permission from or contact with the system administrator.

It is worth pointing out that precisely who controls what can get more complex if real usernames have extension separator characters (a hyphen, by default) in them. For example, if the address postmaster@example.com is rewritten to be foo-postmaster@example.com, it is typically delivered according to the instructions in ~foo/.qmail-postmaster or, if that file does not exist, ~foo/.qmail-default.

However, if there is a user named foo-postmaster, that user will receive email addressed to postmaster@example.com.

If a .qmail file (such as ~foo/.qmail-postmaster) cannot be located for a given extension address (such as foo-postmaster@example.com), the alias user’s directory is checked for .qmail files. Specifically, .qmail-foo-postmaster, .qmail-foo-default, and .qmail-default. If none of these files exist, the message is considered undeliverable and is bounced.

Note that during delivery of such an email, the standard environment variables are defined per the rewritten destination rather than per the original address. For example, if a message addressed to postmaster@example.com is delivered using the example configuration, the affected environment variables will be defined as follows (assuming foo’s home directory is /home/foo):