summaryrefslogtreecommitdiffstats
path: root/README_FILES/VIRTUAL_README
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-06 01:46:30 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-06 01:46:30 +0000
commitb5896ba9f6047e7031e2bdee0622d543e11a6734 (patch)
treefd7b460593a2fee1be579bec5697e6d887ea3421 /README_FILES/VIRTUAL_README
parentInitial commit. (diff)
downloadpostfix-upstream.tar.xz
postfix-upstream.zip
Adding upstream version 3.4.23.upstream/3.4.23upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'README_FILES/VIRTUAL_README')
-rw-r--r--README_FILES/VIRTUAL_README483
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..6f470ee
--- /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 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 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 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.
+