diff options
Diffstat (limited to 'proto/VIRTUAL_README.html')
| -rw-r--r-- | proto/VIRTUAL_README.html | 648 |
1 files changed, 648 insertions, 0 deletions
diff --git a/proto/VIRTUAL_README.html b/proto/VIRTUAL_README.html new file mode 100644 index 0000000..ac11f19 --- /dev/null +++ b/proto/VIRTUAL_README.html @@ -0,0 +1,648 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<html> + +<head> + +<title>Postfix Virtual Domain Hosting Howto</title> + +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + +</head> + +<body> + +<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix +Virtual Domain Hosting Howto</h1> + +<hr> + +<h2>Purpose of this document</h2> + +<p> This document requires Postfix version 2.0 or later. </p> + +<p> 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. </p> + +<p> The text not only describes delivery mechanisms that are built +into Postfix, but also gives pointers for using non-Postfix mail +delivery software. </p> + +<p> The following topics are covered: </p> + +<ul> + +<li> <a href="#canonical">Canonical versus hosted versus other domains</a> + +<li> <a href="#local_vs_database">Local files versus network databases</a> + +<li> <a href="#local">As simple as can be: shared domains, +UNIX system accounts</a> + +<li> <a href="#virtual_alias">Postfix virtual ALIAS example: +separate domains, UNIX system accounts</a> + +<li> <a href="#virtual_mailbox">Postfix virtual MAILBOX example: +separate domains, non-UNIX accounts</a> + +<li> <a href="#in_virtual_other">Non-Postfix mailbox store: separate +domains, non-UNIX accounts</a> + +<li> <a href="#forwarding">Mail forwarding domains</a> + +<li> <a href="#mailing_lists">Mailing lists</a> + +<li> <a href="#autoreplies">Autoreplies</a> + +</ul> + +<h2><a name="canonical">Canonical versus hosted versus +other domains</a></h2> + +<p>Most Postfix systems are <b>final destination</b> 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.</p> + +<p> Besides the canonical domains, Postfix can be configured to be +<b>final destination</b> 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. </p> + +<p> But wait! There is more. Postfix can be configured as a backup +MX host for other domains. In this case Postfix is <b>not the final +destination</b> 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. </p> + +<p> Finally, Postfix can be configured as a transit host for sending +mail across the internet. Obviously, Postfix is not 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. </p> + +<h2><a name="local_vs_database">Local files versus network databases</a></h2> + +<p> The examples in this text use table lookups from local files +such as DBM or Berkeley DB. These are easy to debug with the +<b>postmap</b> command: </p> + +<blockquote> +Example: <tt>postmap -q info@example.com hash:/etc/postfix/virtual</tt> +</blockquote> + +<p> See the documentation in LDAP_README, MYSQL_README and PGSQL_README +for how to replace local files by databases. The reader is strongly +advised to make the system work with local files before migrating +to network databases, and to use the <b>postmap</b> command to verify +that network database lookups produce the exact same results as +local file lookup. </p> + +<blockquote> +Example: <tt>postmap -q info@example.com ldap:/etc/postfix/virtual.cf</tt> +</blockquote> + +<h2><a name="local">As simple as can be: shared domains, UNIX system +accounts</a></h2> + +<p> 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. </p> + +<p> This approach makes no distinction between canonical and hosted +domains. Each username can receive mail in every domain. </p> + +<p> In the examples we will use "example.com" as the domain that is +being hosted on the local Postfix machine. </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + mydestination = $myhostname localhost.$mydomain ... example.com +</pre> +</blockquote> + +<p> The limitations of this approach are: </p> + +<ul> + +<li>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. + +<li> With users in the UNIX password file, administration of large +numbers of users becomes inconvenient. + +</ul> + +<p> The examples that follow provide solutions for both limitations. +</p> + +<h2><a name="virtual_alias">Postfix virtual ALIAS example: +separate domains, UNIX system accounts</a></h2> + +<p> 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. </p> + +<p> 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. +</p> + +<blockquote> +<pre> + 1 /etc/postfix/main.cf: + 2 virtual_alias_domains = example.com ...other hosted domains... + 3 virtual_alias_maps = hash:/etc/postfix/virtual + 4 + 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... +</pre> +</blockquote> + +<p> Notes: </p> + +<ul> + +<li> <p> 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). </p> + +<p> NEVER list a virtual alias domain name as a mydestination +domain! </p> + +<li> <p> 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". </p> + +<li> <p> 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. +</p> + +</ul> + +<p>Execute the command "<b>postmap /etc/postfix/virtual</b>" after +changing the virtual file, and execute the command "<b>postfix +reload</b>" after changing the main.cf file. </p> + +<p> 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. </p> + +<p> More details about the virtual alias file are given in the +virtual(5) manual page, including multiple addresses on the right-hand +side. </p> + +<p> 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. </p> + +<h2><a name="virtual_mailbox">Postfix virtual MAILBOX example: +separate domains, non-UNIX accounts</a></h2> + +<p> As a system hosts more and more domains and users, it becomes less +desirable to give every user their own UNIX system account.</p> + +<p> 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.</p> + +<p> 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 "/".</p> + +<p> 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 <a +href="#local_vs_database"> "local files versus databases"</a> +section at the top of this document.</p> + +<p> Here is an example of a virtual mailbox domain "example.com": +</p> + +<blockquote> +<pre> + 1 /etc/postfix/main.cf: + 2 virtual_mailbox_domains = example.com ...more domains... + 3 virtual_mailbox_base = /var/mail/vhosts + 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox + 5 virtual_minimum_uid = 100 + 6 virtual_uid_maps = static:5000 + 7 virtual_gid_maps = static:5000 + 8 virtual_alias_maps = hash:/etc/postfix/virtual + 9 +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 +</pre> +</blockquote> + +<p> Notes: </p> + +<ul> + +<li> <p> 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). </p> + +<p> NEVER list a virtual MAILBOX domain name as a mydestination +domain! </p> + +<p> NEVER list a virtual MAILBOX domain name as a virtual ALIAS +domain! </p> + +<li> <p> 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. </p> + +<li> <p> 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/. </p> + +<li> <p> 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. </p> + +<li> <p> 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. +</p> + +<li> <p> 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. </p> + +<p> NEVER put a virtual MAILBOX wild-card in the virtual ALIAS +file!! </p> + +<li> <p> 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. </p> + +<li> <p> 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. </p> + +</ul> + +<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after +changing the virtual file, execute "<b>postmap /etc/postfix/vmailbox</b>" +after changing the vmailbox file, and execute the command "<b>postfix +reload</b>" after changing the main.cf file. </p> + +<p> 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. </p> + +<p> More details about the virtual mailbox delivery agent are given +in the virtual(8) manual page. </p> + +<h2><a name="in_virtual_other">Non-Postfix mailbox store: separate +domains, non-UNIX accounts</a></h2> + +<p> 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. </p> + +<p> 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. </p> + +<p> 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. +</p> + +<p> Here is an example for a hosted domain example.com that delivers +to a non-Postfix delivery agent: </p> + +<blockquote> +<pre> + 1 /etc/postfix/main.cf: + 2 virtual_transport = ...see below... + 3 virtual_mailbox_domains = example.com ...more domains... + 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox + 5 virtual_alias_maps = hash:/etc/postfix/virtual + 6 + 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 +</pre> +</blockquote> + +<p> Notes: </p> + +<ul> + +<li> <p> 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): </p> + +<blockquote> +<pre> +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) +</pre> +</blockquote> + +<p> 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. +</p> + +<li> <p> 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). </p> + +<p> NEVER list a virtual MAILBOX domain name as a mydestination +domain! </p> + +<p> NEVER list a virtual MAILBOX domain name as a virtual ALIAS +domain! </p> + +<li> <p> 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 <a href="#local_vs_database"> "local files versus databases"</a> +section at the top of this document! </p> + +<li> <p> 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. </p> + +<p> NEVER put a virtual MAILBOX wild-card in the virtual ALIAS +file!! </p> + +<p> 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. </p> + +<li> <p> 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. </p> + +<li> <p> 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. </p> + +</ul> + +<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after +changing the virtual file, execute "<b>postmap /etc/postfix/vmailbox</b>" +after changing the vmailbox file, and execute the command "<b>postfix +reload</b>" after changing the main.cf file. </p> + +<h2><a name="forwarding">Mail forwarding domains</a></h2> + +<p> 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: </p> + +<blockquote> +<pre> + 1 /etc/postfix/main.cf: + 2 virtual_alias_domains = example.com ...other hosted domains... + 3 virtual_alias_maps = hash:/etc/postfix/virtual + 4 + 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... +</pre> +</blockquote> + +<p> Notes: </p> + +<ul> + +<li> <p> 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). </p> + +<p> NEVER list a virtual alias domain name as a mydestination +domain! </p> + +<li> <p> 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". </p> + +<li> <p> 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. +</p> + +</ul> + +<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after +changing the virtual file, and execute the command "<b>postfix +reload</b>" after changing the main.cf file. </p> + +<p> More details about the virtual alias file are given in the +virtual(5) manual page, including multiple addresses on the right-hand +side. </p> + +<h2><a name="mailing_lists">Mailing lists</a></h2> + +<p> 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. </p> + +<p> 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: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + virtual_alias_maps = hash:/etc/postfix/virtual + +/etc/postfix/virtual: + listname-request@example.com listname-request + listname@example.com listname + owner-listname@example.com owner-listname + +/etc/aliases: + listname: "|/some/where/majordomo/wrapper ..." + owner-listname: ... + listname-request: ... +</pre> +</blockquote> + +<p> 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. </p> + +<p> More information about the Postfix local delivery agent can be +found in the local(8) manual page. </p> + +<p> 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. </p> + +<ul> + +<li> In case of a virtual alias domain, there would need to be one +identity mapping from each mailing list address to itself. + +<li> In case of a virtual mailbox domain, there would need to be +a dummy mailbox for each mailing list address. + +</ul> + +<h2><a name="autoreplies">Autoreplies</a></h2> + +<p> In order to set up an autoreply for virtual recipients while +still delivering mail as normal, set up a rule in a virtual alias +table: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + virtual_alias_maps = hash:/etc/postfix/virtual + +/etc/postfix/virtual: + user@domain.tld user@domain.tld, user@domain.tld@autoreply.mydomain.tld +</pre> +</blockquote> + +<p> This delivers mail to the recipient, and sends a copy of the +mail to the address that produces automatic replies. The address +can be serviced on a different machine, or it can be serviced +locally by setting up a transport map entry that pipes all mail +for autoreply.mydomain.tld into some script that sends an automatic +reply back to the sender. </p> + +<p> DO NOT list autoreply.mydomain.tld in mydestination! </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + transport_maps = hash:/etc/postfix/transport + +/etc/postfix/transport: + autoreply.mydomain.tld autoreply: + +/etc/postfix/master.cf: + # ============================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ============================================================= + autoreply unix - n n - - pipe + flags= user=nobody argv=/path/to/autoreply $sender $mailbox +</pre> +</blockquote> + +<p> This invokes /path/to/autoreply with the sender address and +the user@domain.tld recipient address on the command line. </p> + +<p> For more information, see the pipe(8) manual page, and the +comments in the Postfix master.cf file. </p> + +</body> + +</html> |