Postfix Virtual Domain Hosting Howto

Postfix Virtual Domain Hosting Howto
Postfix
Virtual Domain Hosting Howto
Purpose of this document
This document requires Postfix version 2.0 or later.
This document gives an overview of how Postfix can be used for
hosting multiple Internet domains, both for final delivery on the
machine itself and for the purpose of forwarding to destinations
elsewhere.
The text not only describes delivery mechanisms that are built
into Postfix, but also gives pointers for using non-Postfix mail
delivery software.
The following topics are covered:
Canonical versus hosted versus other domains
Local files versus network databases
As simple as can be: shared domains,
UNIX system accounts
Postfix virtual ALIAS example:
separate domains, UNIX system accounts
Postfix virtual MAILBOX example:
separate domains, non-UNIX accounts
Non-Postfix mailbox store: separate
domains, non-UNIX accounts
Mail forwarding domains
Hosted mailing list domains
Canonical versus hosted versus
other domains
Most Postfix systems are the
final destination
for only a
few domain names. These include the hostnames and [the IP addresses]
of the machine that Postfix runs on, and sometimes also include
the parent domain of the hostname. The remainder of this document
will refer to these domains as the
canonical domains
. They are
usually implemented with the Postfix
local domain
address class,
as defined in the
ADDRESS_CLASS_README
file.
Besides the
canonical domains
, Postfix can be configured to be
the
final destination
for any number of additional domains.
These domains are called hosted, because they are not directly
associated with the name of the machine itself. Hosted domains are
usually implemented with the
virtual alias domain
address class
and/or with the
virtual mailbox domain
address class, as defined
in the
ADDRESS_CLASS_README
file.
But wait! There is more. Postfix can be configured as a backup
MX host for other domains. In this case Postfix is
not the final
destination
for those domains. It merely queues the mail when
the primary MX host is down, and forwards the mail when the primary
MX host becomes available. This function is implemented with the
relay domain
address class, as defined in the
ADDRESS_CLASS_README
file.
Finally, Postfix can be configured as a transit host for sending
mail across the internet. Obviously, Postfix is not the final destination
for such mail. This function is available only for authorized
clients and/or users, and is implemented by the
default domain
address class, as defined in the
ADDRESS_CLASS_README
file.
Local files versus network databases
The examples in this text use table lookups from local files
such as
lmdb
:,
cdb
:,
hash
:, or
dbm
:. These are easy to debug with the
postmap
command:
Example:
postmap -q info@example.com /etc/postfix/virtual
The above example assumes that the database is configured in
main.cf
as $
default_database_type
:/etc/postfix/virtual. Otherwise,
use the command instead:
Example:
postmap -q info@example.com
type
:/etc/postfix/virtual
and specify the explicit type that this table uses in
main.cf
You can replace local file lookups with networked (LDAP, SQL
etc.) lookups. See the documentation in
LDAP_README
MYSQL_README
PGSQL_README
, etc., for examples. The reader is strongly advised
to make Postfix work with local files before migrating to network
databases, and to use the
postmap
command to verify that
network database lookups produce the exact same results as local
file lookup.
Example:
postmap -q info@example.com
ldap
:/etc/postfix/virtual.cf
As simple as can be: shared domains, UNIX system
accounts
The simplest method to host an additional domain is to add the
domain name to the domains listed in the Postfix
mydestination
configuration parameter, and to add the user names to the UNIX
password file.
This approach makes no distinction between canonical and hosted
domains. Each username can receive mail in every domain.
In the examples we will use "example.com" as the domain that is
being hosted on the local Postfix machine.
/etc/postfix/
main.cf
mydestination
= $
myhostname
localhost.$
mydomain
... example.com
The limitations of this approach are:
A total lack of separation: mail for info@my.host.name is
delivered to the same UNIX system account as mail for info@example.com.
With users in the UNIX password file, administration of large
numbers of users becomes inconvenient.
The examples that follow provide solutions for both limitations.
Postfix virtual ALIAS example:
separate domains, UNIX system accounts
With the approach described in this section, every
hosted domain
can have its own info etc. email address. However, it still uses
UNIX system accounts for local mailbox deliveries.
With
virtual alias domains
, each hosted address is aliased to
a local UNIX system account or to a remote address. The example
below shows how to use this mechanism for the example.com domain.
1 /etc/postfix/
main.cf
virtual_alias_domains
= example.com ...other
hosted domains
...
virtual_alias_maps
lmdb
:/etc/postfix/virtual
5 /etc/postfix/virtual:
6 postmaster@example.com postmaster
7 info@example.com joe
8 sales@example.com jane
9 # Uncomment entry below to implement a catch-all address
10 # @example.com jim
11 ...virtual aliases for more domains...
Notes:
Line 2: the
virtual_alias_domains
setting tells Postfix
that example.com is a so-called
virtual alias domain
. If you omit
this setting then Postfix will reject mail (relay access denied)
or will not be able to deliver it (mail for example.com loops back
to myself).
NEVER list a
virtual alias domain
name as a
mydestination
domain!
Lines 3-8: the /etc/postfix/virtual file contains the virtual
aliases. With the example above, mail for postmaster@example.com
goes to the local postmaster, while mail for info@example.com goes
to the UNIX account joe, and mail for sales@example.com goes to
the UNIX account jane. Mail for all other addresses in example.com
is rejected with the error message "User unknown".
Line 10: the commented out entry (text after #) shows how
one would implement a catch-all virtual alias that receives mail
for every example.com address not listed in the virtual alias file.
This is not without risk. Spammers nowadays try to send mail from
(or mail to) every possible name that they can think of. A catch-all
mailbox is likely to receive many spam messages, and many bounces
for spam messages that were sent in the name of anything@example.com.
Instead of
lmdb
:, some systems use
cdb
:,
hash
:, or
dbm
:.
Execute the command "
postmap /etc/postfix/virtual
" after
changing the virtual file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/virtual
" to specify
an explicit type.
The default indexed file type is configured with the
default_database_type
parameter. To list available explicit types,
execute the command "
postconf -m
".
Execute the command "
postfix
reload
" after changing the
main.cf
file.
Note: virtual aliases can resolve to a local address or to a
remote address, or both. They don't have to resolve to UNIX system
accounts on your machine.
More details about the virtual alias file are given in the
virtual(5)
manual page, including multiple addresses on the right-hand
side.
Virtual aliasing solves one problem: it allows each domain to
have its own info mail address. But there still is one drawback:
each virtual address is aliased to a UNIX system account. As you
add more virtual addresses you also add more UNIX system accounts.
The next section eliminates this problem.
Postfix virtual MAILBOX example:
separate domains, non-UNIX accounts
As a system hosts more and more domains and users, it becomes less
desirable to give every user their own UNIX system account.
With the Postfix
virtual(8)
mailbox delivery agent, every
recipient address can have its own virtual mailbox. Unlike virtual
alias domains,
virtual mailbox domains
do not need the clumsy
translation from each recipient addresses into a different address,
and owners of a virtual mailbox address do not need to have a UNIX
system account.
The Postfix
virtual(8)
mailbox delivery agent looks up the user
mailbox pathname, uid and gid via separate tables that are searched
with the recipient's mail address. Maildir style delivery is turned
on by terminating the mailbox pathname with "/".
If you find the idea of multiple tables bothersome, remember
that you can migrate the information (once it works), to an SQL
database. If you take that route, be sure to review the
"local files versus databases"
section at the top of this document.
Here is an example of a
virtual mailbox domain
"example.com":
1 /etc/postfix/
main.cf
virtual_mailbox_domains
= example.com ...more domains...
virtual_mailbox_base
= /var/mail/vhosts
virtual_mailbox_maps
lmdb
:/etc/postfix/vmailbox
virtual_minimum_uid
= 100
virtual_uid_maps
static
:5000
virtual_gid_maps
static
:5000
virtual_alias_maps
lmdb
:/etc/postfix/virtual
10 /etc/postfix/vmailbox:
11 info@example.com example.com/info
12 sales@example.com example.com/sales/
13 # Comment out the entry below to implement a catch-all.
14 # @example.com example.com/catchall
15 ...virtual mailboxes for more domains...
16
17 /etc/postfix/virtual:
18 postmaster@example.com postmaster
Notes:
Line 2: The
virtual_mailbox_domains
setting tells Postfix
that example.com is a so-called
virtual mailbox domain
. If you omit
this setting then Postfix will reject mail (relay access denied)
or will not be able to deliver it (mail for example.com loops back
to myself).
NEVER list a
virtual MAILBOX domain
name as a
mydestination
domain!
NEVER list a
virtual MAILBOX domain
name as a virtual ALIAS
domain!
Line 3: The
virtual_mailbox_base
parameter specifies a
prefix for all virtual mailbox pathnames. This is a safety mechanism
in case someone makes a mistake. It prevents mail from being
delivered all over the file system.
Lines 4, 10-15: The
virtual_mailbox_maps
parameter specifies
the lookup table with mailbox (or maildir) pathnames, indexed by
the virtual mail address. In this example, mail for info@example.com
goes to the mailbox at /var/mail/vhosts/example.com/info while mail
for sales@example.com goes to the maildir located at
/var/mail/vhosts/example.com/sales/.
Line 5: The
virtual_minimum_uid
specifies a lower bound
on the mailbox or maildir owner's UID. This is a safety mechanism
in case someone makes a mistake. It prevents mail from being written
to sensitive files.
Lines 6, 7: The
virtual_uid_maps
and
virtual_gid_maps
parameters specify that all the virtual mailboxes are owned by a
fixed uid and gid 5000. If this is not what you want, specify
lookup tables that are searched by the recipient's mail address.
Line 14: The commented out entry (text after #) shows how
one would implement a catch-all virtual mailbox address. Be prepared
to receive a lot of spam, as well as bounced spam that was sent in
the name of anything@example.com.
NEVER put a virtual MAILBOX wild-card in the virtual ALIAS
file!!
Lines 8, 17, 18: As you see, it is possible to mix virtual
aliases with virtual mailboxes. We use this feature to redirect
mail for example.com's postmaster address to the local postmaster.
You can use the same mechanism to redirect an address to a remote
address.
Line 18: This example assumes that in
main.cf
, $
myorigin
is listed under the
mydestination
parameter setting. If that is
not the case, specify an explicit domain name on the right-hand
side of the virtual alias table entries or else mail will go to
the wrong domain.
Instead of
lmdb
:, some systems use
cdb
:,
hash
:, or
dbm
:.
Execute the command "
postmap /etc/postfix/virtual
" after
changing the virtual file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/virtual
" to specify
an explicit type.
The default indexed file type is configured with the
default_database_type
parameter. To list available explicit types,
execute the command "
postconf -m
".
Execute "
postmap /etc/postfix/vmailbox
" after changing
the vmailbox file, to (re)build a default-type indexed file. Execute
postmap
type
:/etc/postfix/vmailbox
" to specify an
explicit type.
Execute the command "
postfix reload
" after changing the
main.cf
file.
Note: mail delivery happens with the recipient's UID/GID
privileges specified with
virtual_uid_maps
and
virtual_gid_maps
Postfix 2.0 and earlier will not create mailDIRs in world-writable
parent directories; you must create them in advance before you can
use them. Postfix may be able to create mailBOX files by itself,
depending on parent directory write permissions, but it is safer
to create mailBOX files ahead of time.
More details about the virtual mailbox delivery agent are given
in the
virtual(8)
manual page.
Non-Postfix mailbox store: separate
domains, non-UNIX accounts
This is a variation on the Postfix
virtual mailbox example
Again, every hosted address can have its own mailbox. However, most
parameters that control the
virtual(8)
delivery agent are no longer
applicable: only
virtual_mailbox_domains
and
virtual_mailbox_maps
stay in effect. These parameters are needed to reject mail for
unknown recipients.
While non-Postfix software is being used for final delivery,
some Postfix concepts are still needed in order to glue everything
together. For additional background on this glue you may want to
take a look at the
virtual mailbox domain
class as defined in the
ADDRESS_CLASS_README
file.
The text in this section describes what things should look like
from Postfix's point of view. See
CYRUS_README
or
MAILDROP_README
for specific information about Cyrus or about Courier maildrop.
Here is an example for a
hosted domain
example.com that delivers
to a non-Postfix delivery agent:
1 /etc/postfix/
main.cf
virtual_transport
= ...see below...
virtual_mailbox_domains
= example.com ...more domains...
virtual_mailbox_maps
lmdb
:/etc/postfix/vmailbox
virtual_alias_maps
lmdb
:/etc/postfix/virtual
7 /etc/postfix/vmailbox:
8 info@example.com whatever
9 sales@example.com whatever
10 # Comment out the entry below to implement a catch-all.
11 # Configure the mailbox store to accept all addresses.
12 # @example.com whatever
13 ...virtual mailboxes for more domains...
14
15 /etc/postfix/virtual:
16 postmaster@example.com postmaster
Notes:
Line 2: With delivery to a non-Postfix mailbox store for
hosted domains
, the
virtual_transport
parameter usually specifies
the Postfix LMTP client, or the name of a
master.cf
entry that
executes non-Postfix software via the pipe delivery agent. Typical
examples (use only one):
virtual_transport
lmtp
:unix:/path/name (uses UNIX-domain socket)
virtual_transport
lmtp
:hostname:port (uses TCP socket)
virtual_transport
= maildrop: (uses
pipe(8)
to command)
Postfix comes ready with support for LMTP. And an example
maildrop delivery method is already defined in the default Postfix
master.cf
file. See the
MAILDROP_README
document for more details.
Line 3: The
virtual_mailbox_domains
setting tells Postfix
that example.com is delivered via the
virtual_transport
that was
discussed in the previous paragraph. If you omit this
virtual_mailbox_domains
setting then Postfix will either reject
mail (relay access denied) or will not be able to deliver it (mail
for example.com loops back to myself).
NEVER list a
virtual MAILBOX domain
name as a
mydestination
domain!
NEVER list a
virtual MAILBOX domain
name as a virtual ALIAS
domain!
Lines 4, 7-13: The
virtual_mailbox_maps
parameter specifies
the lookup table with all valid recipient addresses. The lookup
result value is ignored by Postfix. In the above example,
info@example.com
and sales@example.com are listed as valid addresses; other mail for
example.com is rejected with "User unknown" by the Postfix SMTP
server. It's left up to the non-Postfix delivery agent to reject
non-existent recipients from local submission or from local alias
expansion. If you intend to
use LDAP, MySQL or PgSQL instead of local files, be sure to review
the
"local files versus databases"
section at the top of this document!
Line 12: The commented out entry (text after #) shows how
one would inform Postfix of the existence of a catch-all address.
Again, the lookup result is ignored by Postfix.
NEVER put a virtual MAILBOX wild-card in the virtual ALIAS
file!!
Note: if you specify a wildcard in
virtual_mailbox_maps
, then
you still need to configure the non-Postfix mailbox store to receive
mail for any address in that domain.
Lines 5, 15, 16: As you see above, it is possible to mix
virtual aliases with virtual mailboxes. We use this feature to
redirect mail for example.com's postmaster address to the local
postmaster. You can use the same mechanism to redirect any addresses
to a local or remote address.
Line 16: This example assumes that in
main.cf
, $
myorigin
is listed under the
mydestination
parameter setting. If that is
not the case, specify an explicit domain name on the right-hand
side of the virtual alias table entries or else mail will go to
the wrong domain.
Instead of
lmdb
:, some systems use
cdb
:,
hash
:, or
dbm
:.
Execute the command "
postmap /etc/postfix/virtual
" after
changing the virtual file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/virtual
" to specify
an explicit type.
The default indexed file type is configured with the
default_database_type
parameter. To list available explicit types,
execute the command "
postconf -m
".
Execute the command "
postmap /etc/postfix/vmailbox
" after
changing the vmailbox file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/vmailbox
" to
specify an explicit type.
Execute the command "
postfix reload
" after changing the
main.cf
file.
Mail forwarding domains
Some providers host domains that have no (or only a few) local
mailboxes. The main purpose of these domains is to forward mail
elsewhere. The following example shows how to set up example.com
as a mail forwarding domain:
1 /etc/postfix/
main.cf
virtual_alias_domains
= example.com ...other
hosted domains
...
virtual_alias_maps
lmdb
:/etc/postfix/virtual
5 /etc/postfix/virtual:
6 postmaster@example.com postmaster
7 joe@example.com joe@somewhere
8 jane@example.com jane@somewhere-else
9 # Uncomment entry below to implement a catch-all address
10 # @example.com jim@yet-another-site
11 ...virtual aliases for more domains...
Notes:
Line 2: The
virtual_alias_domains
setting tells Postfix
that example.com is a so-called
virtual alias domain
. If you omit
this setting then Postfix will reject mail (relay access denied)
or will not be able to deliver it (mail for example.com loops back
to myself).
NEVER list a
virtual alias domain
name as a
mydestination
domain!
Lines 3-11: The /etc/postfix/virtual file contains the
virtual aliases. With the example above, mail for postmaster@example.com
goes to the local postmaster, while mail for joe@example.com goes
to the remote address joe@somewhere, and mail for jane@example.com
goes to the remote address jane@somewhere-else. Mail for all other
addresses in example.com is rejected with the error message "User
unknown".
Line 10: The commented out entry (text after #) shows how
one would implement a catch-all virtual alias that receives mail
for every example.com address not listed in the virtual alias file.
This is not without risk. Spammers nowadays try to send mail from
(or mail to) every possible name that they can think of. A catch-all
mailbox is likely to receive many spam messages, and many bounces
for spam messages that were sent in the name of anything@example.com.
Instead of
lmdb
:, some systems use
cdb
:,
hash
:, or
dbm
:.
Execute the command "
postmap /etc/postfix/virtual
" after
changing the virtual file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/virtual
" to specify
an explicit type.
The default indexed file type is configured with the
default_database_type
parameter. To list available explicit types,
execute the command "
postconf -m
".
Execute the command "
postfix reload
" after changing the
main.cf
file.
More details about the virtual alias file are given in the
virtual(5)
manual page, including multiple addresses on the right-hand
side.
Hosted mailing list domains
Note: this section presents a historical approach to run a
mailing list based on local
aliases(5)
. This approach may still be
useful for small mailing lists that are managed by hand or with the
software like Majordomo. For a more contemporary and more scalable
approach, see
GNU Mailman
The examples that were given above already show how to direct
mail for virtual postmaster addresses to a local postmaster. You
can use the same method to direct mail for any address to a local
or remote address.
There is one major limitation: virtual aliases and virtual
mailboxes can't directly deliver to mailing list managers such as
majordomo. The solution is to set up virtual aliases that direct
virtual addresses to the local delivery agent:
/etc/postfix/
main.cf
virtual_alias_maps
lmdb
:/etc/postfix/virtual
virtual_mailbox_domains
= example.com

/etc/postfix/virtual:
listname-request@example.com listname-request
listname@example.com listname
owner-listname@example.com owner-listname
postmaster@example.com postmaster

/etc/aliases:
listname: "|/some/where/majordomo/wrapper ..."
owner-listname: ...
listname-request: ...
Instead of
lmdb
:, some systems use
cdb
:,
hash
:, or
dbm
:.
Execute the command "
postmap /etc/postfix/virtual
" after
changing the virtual file, to (re)build a default-type indexed file.
Execute "
postmap
type
:/etc/postfix/virtual
" to specify
an explicit type.
The default indexed file type is configured with the
default_database_type
parameter. To list available explicit types,
execute the command "
postconf -m
".
This example assumes that in
main.cf
, $
myorigin
is listed under
the
mydestination
parameter setting. If that is not the case,
specify an explicit domain name on the right-hand side of the
virtual alias table entries or else mail will go to the wrong
domain.
More information about the Postfix local delivery agent can be
found in the
local(8)
manual page.
Why does this example use a clumsy virtual alias instead of a
more elegant transport mapping? The reason is that mail for the
virtual mailing list would be rejected with "User unknown". In
order to make the transport mapping work one would still need a
bunch of virtual alias or virtual mailbox table entries.
In the case of a virtual alias DOMAIN, there would need to be
an identity mapping from each mailing list address to an address in a
different domain.
In the case of a virtual mailbox DOMAIN, there would need to
be a dummy
virtual_mailbox_maps
for each mailing list address.