diff options
Diffstat (limited to 'README_FILES/VIRTUAL_README')
| -rw-r--r-- | README_FILES/VIRTUAL_README | 483 |
1 files changed, 483 insertions, 0 deletions
diff --git a/README_FILES/VIRTUAL_README b/README_FILES/VIRTUAL_README new file mode 100644 index 0000000..e693a0c --- /dev/null +++ b/README_FILES/VIRTUAL_README @@ -0,0 +1,483 @@ +PPoossttffiixx VViirrttuuaall DDoommaaiinn HHoossttiinngg HHoowwttoo + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff tthhiiss ddooccuummeenntt + +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 + * Mailing lists + * Autoreplies + +CCaannoonniiccaall vveerrssuuss hhoosstteedd vveerrssuuss ootthheerr ddoommaaiinnss + +Most Postfix systems are the ffiinnaall ddeessttiinnaattiioonn 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 ffiinnaall +ddeessttiinnaattiioonn 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 nnoott tthhee ffiinnaall ddeessttiinnaattiioonn 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. + +LLooccaall ffiilleess vveerrssuuss nneettwwoorrkk ddaattaabbaasseess + +The examples in this text use table lookups from local files such as DBM or +Berkeley DB. These are easy to debug with the ppoossttmmaapp command: + + Example: postmap -q info@example.com hash:/etc/postfix/virtual + +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 ppoossttmmaapp 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 + +AAss ssiimmppllee aass ccaann bbee:: sshhaarreedd ddoommaaiinnss,, UUNNIIXX ssyysstteemm aaccccoouunnttss + +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. + +PPoossttffiixx vviirrttuuaall AALLIIAASS eexxaammppllee:: sseeppaarraattee ddoommaaiinnss,, UUNNIIXX ssyysstteemm aaccccoouunnttss + +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: + 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... + +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. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, and execute the command "ppoossttffiixx rreellooaadd" 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. + +PPoossttffiixx vviirrttuuaall MMAAIILLBBOOXX eexxaammppllee:: sseeppaarraattee ddoommaaiinnss,, nnoonn--UUNNIIXX aaccccoouunnttss + +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: + 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 + +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. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, execute "ppoossttmmaapp //eettcc//ppoossttffiixx//vvmmaaiillbbooxx" after changing the vmailbox file, +and execute the command "ppoossttffiixx rreellooaadd" 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. + +NNoonn--PPoossttffiixx mmaaiillbbooxx ssttoorree:: sseeppaarraattee ddoommaaiinnss,, nnoonn--UUNNIIXX aaccccoouunnttss + +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: + 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 + +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. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, execute "ppoossttmmaapp //eettcc//ppoossttffiixx//vvmmaaiillbbooxx" after changing the vmailbox file, +and execute the command "ppoossttffiixx rreellooaadd" after changing the main.cf file. + +MMaaiill ffoorrwwaarrddiinngg ddoommaaiinnss + +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: + 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... + +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. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, and execute the command "ppoossttffiixx rreellooaadd" 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. + +MMaaiilliinngg lliissttss + +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 = 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: ... + +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 case of a virtual alias domain, there would need to be one identity + mapping from each mailing list address to itself. + * In case of a virtual mailbox domain, there would need to be a dummy mailbox + for each mailing list address. + +AAuuttoorreepplliieess + +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: + + /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 + +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. + +DO NOT list autoreply.mydomain.tld in mydestination! + + /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 + +This invokes /path/to/autoreply with the sender address and the user@domain.tld +recipient address on the command line. + +For more information, see the pipe(8) manual page, and the comments in the +Postfix master.cf file. + |