This is the first patch to Postfix 19991231. It fixes no bugs but
rather adds a safety net for a common configuration problem.

A common error is to list Postfix virtual domains in the mydestination
parameter. This causes the new optional local_recipient_maps feature
to reject mail for virtual users.  Postfix now explicitly tests
for this condition and logs a warning instead of refusing the mail.

The patch is too large for email. It adds only a few lines of code.
The bulk of the patch is spent on clarification in the documentation
and in the sample configuration files, plus some feedback on the
documentation that I received over the last couple days.

The patch, postfix-19991231-patch01.gz, and a complete source kit,
postfix-19991231-pl01.tar.gz, will be made available from the
primary site:

   ftp://ftp.porcupine.org/mirrors/postfix-release/official/
   http://ftp.porcupine.org/mirrors/postfix-release/index.html

including a PGP signature (postfix-19991231-pl01.tar.gz.sig).

	Wietse

Prereq: "Postfix-19991231"
diff -cr /tmp/postfix-19991231/global/mail_version.h ./global/mail_version.h
*** /tmp/postfix-19991231/global/mail_version.h	Fri Dec 31 16:18:04 1999
--- ./global/mail_version.h	Sun Jan  2 12:38:15 2000
***************
*** 15,21 ****
    * Version of this program.
    */
  #define VAR_MAIL_VERSION	"mail_version"
! #define DEF_MAIL_VERSION	"Postfix-19991231"
  extern char *var_mail_version;
  
  /* LICENSE
--- 15,21 ----
    * Version of this program.
    */
  #define VAR_MAIL_VERSION	"mail_version"
! #define DEF_MAIL_VERSION	"Postfix-19991231-pl01"
  extern char *var_mail_version;
  
  /* LICENSE
diff -cr /tmp/postfix-19991231/HISTORY ./HISTORY
*** /tmp/postfix-19991231/HISTORY	Fri Dec 31 14:41:07 1999
--- ./HISTORY	Sun Jan  2 17:11:48 2000
***************
*** 3515,3517 ****
--- 3515,3529 ----
  	to enable LMTP delivery over UNIX-domain sockets. The goal
  	is to simplify the experimental LMTP delivery agent by
  	ripping out the privileged code that forks the LMTP server.
+ 
+ 20000102
+ 
+ 	Clarified documentation after early feedback on the 19991231
+ 	release by Drew Derbyshire, Ollivier Robert, Khetan Gajjar.
+ 
+ 	Sanity check: a common error is to list Postfix virtual
+ 	domains in the mydestination parameter. This causes the
+ 	new optional local_recipient_maps feature to reject mail
+ 	for virtual users.  The SMTP server now explicitly tests
+ 	for this common error and logs a warning instead of refusing
+ 	the mail.  File:  smtpd/smtpd_check.c.
diff -cr /tmp/postfix-19991231/RELEASE_NOTES ./RELEASE_NOTES
*** /tmp/postfix-19991231/RELEASE_NOTES	Fri Dec 31 18:06:52 1999
--- ./RELEASE_NOTES	Sun Jan  2 12:41:54 2000
***************
*** 76,85 ****
  - The SMTP server now rejects mail for unknown users in virtual
  domains that are defined by Postfix virtual maps.
  
! - The SMTP server optionally rejects mail for unknown local users.
! Use "local_recipient_maps = $alias_maps, unix:passwd.byname" if
! your local mail is delivered by a UNIX-style local delivery agent.
! See example in conf/main.cf.
  
  - Use "disable_vrfy_command = yes" to disable the SMTP VRFY command.
  This prevents some forms of address harvesting.
--- 76,85 ----
  - The SMTP server now rejects mail for unknown users in virtual
  domains that are defined by Postfix virtual maps.
  
! - The SMTP server can reject mail for unknown local users.  Specify
! "local_recipient_maps = $relocated_maps, $alias_maps, unix:passwd.byname"
! if your local mail is delivered by a UNIX-style local delivery
! agent.  See example in conf/main.cf.
  
  - Use "disable_vrfy_command = yes" to disable the SMTP VRFY command.
  This prevents some forms of address harvesting.
diff -cr /tmp/postfix-19991231/conf/main.cf ./conf/main.cf
*** /tmp/postfix-19991231/conf/main.cf	Mon Dec 27 16:03:38 1999
--- ./conf/main.cf	Sun Jan  2 14:19:11 2000
***************
*** 125,131 ****
  # Beware: if the Postfix SMTP server runs chrooted, you may have to
  # copy the passwd database into the jail. This is system dependent.
  #
! #local_recipient_maps = $alias_maps unix:passwd.byname
  
  # ADDRESS REWRITING
  #
--- 125,134 ----
  # Beware: if the Postfix SMTP server runs chrooted, you may have to
  # copy the passwd database into the jail. This is system dependent.
  #
! # FOR THIS TO WORK, DO NOT SPECIFY VIRTUAL DOMAINS IN MYDESTINATION.
! # MYDESTINATION MUST LIST NON-VIRTUAL DOMAINS ONLY.
! #
! #local_recipient_maps = $relocated_maps $alias_maps unix:passwd.byname
  
  # ADDRESS REWRITING
  #
diff -cr /tmp/postfix-19991231/html/faq.html ./html/faq.html
*** /tmp/postfix-19991231/html/faq.html	Fri Dec 31 17:27:19 1999
--- ./html/faq.html	Sun Jan  2 17:24:04 2000
***************
*** 97,104 ****
  
  <li><a href="#mobile">Relaying mail for mobile users</a>
  
! <li><a href="#relay_virtual">Postfix refuses to receive mail for some
! virtual domains</a>
  
  <li><a href="#relay_restrict">Restricting what users can send mail to off-site destinations</a>
  
--- 97,104 ----
  
  <li><a href="#mobile">Relaying mail for mobile users</a>
  
! <li><a href="#virtual_setup">Postfix refuses mail for virtual
! domains with "relay access denied"</a>
  
  <li><a href="#relay_restrict">Restricting what users can send mail to off-site destinations</a>
  
***************
*** 155,166 ****
  
  <ul>
  
! <li><a href="#command">Commands don't work in Postfix virtual maps</a>
  
! <li><a href="#unknown_virtual">Rejecting mail for unknown virtual users</a>
  
! <li><a href="#relay_virtual">Postfix refuses to receive mail for some
! virtual domains</a>
  
  </ul>
  
--- 155,178 ----
  
  <ul>
  
! <li><a href="#virtual_setup">How to configure a Postfix virtual domain</a>
! 
! <li><a href="#virtual_setup">Postfix does not refuse mail for
! unknown virtual users</a>
! 
! <li><a href="#virtual_setup">Mail for unknown virtual users fails
! with "mail loops back to myself"</a>
  
! <li><a href="#virtual_setup">Postfix refuses mail for virtual
! domains with "user unknown"</a>
  
! <li><a href="#virtual_setup">Postfix refuses mail for virtual
! domains with "relay access denied"</a>
! 
! <li><a href="#command">Commands don't work in Postfix virtual maps</a>
! 
! <li><a href="#domain_mailbox">Receiving a virtual domain in a
! mailbox</a>
  
  </ul>
  
***************
*** 1123,1129 ****
  <a name="bogus"><h3>Postfix accepts mail for non-existing local users</h3>
  
  The information in this section applies to Postfix versions 19991216
! and later. See elsewhere for <a href="#unknown_virtual">unknown
  virtual</a> users.
  
  <p>
--- 1135,1141 ----
  <a name="bogus"><h3>Postfix accepts mail for non-existing local users</h3>
  
  The information in this section applies to Postfix versions 19991216
! and later. See elsewhere for <a href="#virtual_setup">unknown
  virtual</a> users.
  
  <p>
***************
*** 1145,1151 ****
  
  <pre>
      <b>/etc/postfix/main.cf</b>:
! 	local_recipient_maps = $alias_maps, unix:passwd.byname
  </pre>
  
  <p>
--- 1157,1163 ----
  
  <pre>
      <b>/etc/postfix/main.cf</b>:
! 	local_recipient_maps = $relocated_maps $alias_maps, unix:passwd.byname
  </pre>
  
  <p>
***************
*** 1527,1532 ****
--- 1539,1603 ----
  
  <hr>
  
+ <a name="virtual_setup"><h3>How to configure a Postfix virtual domain</h3>
+ 
+ Problem:
+ 
+ <p> 
+ 
+ <ul>
+ 
+ <li>Postfix does not refuse mail for unknown virtual users.
+ 
+ <li>Mail for unknown virtual users fails with "mail loops back to
+ myself".
+ 
+ <li>Postfix refuses mail for virtual domains with "user unknown".
+ 
+ <li>Postfix refuses mail for virtual domains with "relay access
+ denied".
+ 
+ </ul>
+ 
+ <p>
+ 
+ Solution:
+ 
+ <p>
+ 
+ <ul>
+ 
+ <li> Add a magical entry to the Postfix virtual maps for
+ each Postfix virtual domain:
+ 
+ <p>
+ 
+ <pre>
+     <b>/etc/postfix/virtual</b>:
+         virtual.domain whatever
+ </pre>
+ 
+ <p>
+ 
+ <li> Do not list Postfix virtual domains in the <a
+ href="basic.html#mydestination">mydestination</a> parameter.
+ 
+ <li> Do not list Postfix virtual maps in the <b>local_recipient_maps</b>
+ parameter.
+ 
+ <li>As of Postfix version 19991226 it is no longer necessary to
+ specify virtual maps in the <a
+ href="uce.html#relay_domains">relay_domains</a> parameter.
+ 
+ </ul>
+ 
+ <p>
+ 
+ For more information on how to set up virtual domains, see the <a
+ href="virtual.5.html">virtual</a> manual page.
+ 
+ <hr>
+ 
  <a name="command"><h3>Commands don't work in Postfix virtual maps</h3>
  
  Delivering mail to a command is a security-sensitive operation,
***************
*** 1593,1659 ****
  
  <hr>
  
! <a name="unknown_virtual"><h3>Rejecting mail for unknown virtual users</h3>
  
! Problem: mail for an unknown virtual user is misdelivered to a local
! user with the same name.
  
  <p>
  
! Problem: mail for an unknown virtual user results in an ugly "mail
! loops back to myself" error from Postfix.
  
  <p>
  
! Solution: add a magical entry to the Postfix virtual database:
  
  <p>
  
! <pre>
!     <b>/etc/postfix/virtual</b>:
!         virtual.domain whatever
! </pre>
  
  <p>
  
! This entry will also fix the problem that the Postfix SMTP server
! refuses to <a href="#relay_virtual">receive</a> mail for the virtual
! domain.
! 
! <p>
! 
! For more information on how to set up virtual domains, see the <a
! href="virtual.5.html">virtual</a> manual page.
! 
! <hr>
! 
! <a name="relay_virtual"><h3>Postfix refuses to receive mail for some
! virtual domains </h3>
  
! In order to receive mail for virtual domains, the Postfix SMTP server
! needs to know that the domain is OK.
  
  <p>
  
  <ul>
  
! <li>Create an entry in the virtual map that lists the virtual
! domain name:
  
! <p>
  
! <pre>
!     <b>/etc/postfix/virtual</b>:
!         virtual.domain      whatever
! </pre>
  
  </ul>
  
- <p>
- 
- For more details, see the <a href="virtual.5.html">virtual</a>
- manual page.
- 
  <hr>
  
  <a name="masquerade"><h3>Address masquerading with exceptions</h3></a>
--- 1664,1732 ----
  
  <hr>
  
! <a name="domain_mailbox"><h3>Receiving a virtual domain in a mailbox</h3>
  
! Question: how to receive all mail for a domain in a mailbox without
! losing the original recipient information? The Postfix Delivered-To:
! mail header shows only the mailbox owner, not the virtual address
! that the mail was sent to.
  
  <p>
  
! Answer: I hope we all agree that delivering a domain to a mailbox
! is disgusting practice. Forwarding mail via SMTP or UUCP would be
! a much better choice.  Unfortunately, neither SMTP nor UUCP are a
! usable alternative for legions of windows users.
  
  <p>
  
! That said, it is possible to propagate the original virtual recipient
! information to the Delivered-To: header. The trick is to use a
! virtual map that uses regular expressions instead of the more
! traditional indexed files.
  
  <p>
  
! The following delivers <i>username@virtual.domain</i> with a
! Delivered-To: message header that contains <i>joe+username@your.domain</i>.
! Postfix already puts the envelope sender address in the Return-Path:
! header.  The information in the Delivered-To: and Return-Path:
! headers is sufficient to reliably implement a domain in a mailbox.
  
  <p>
  
! <pre>
!     <b>/etc/postfix/main.cf</b>
! 	recipient_delimiter = +
! 	virtual_maps = 
! 	    <i>...non-regexp virtual maps...</i>
! 	    regexp:/etc/postfix/virtual_regexp
  
!     <b>/etc/postfix/virtual_regexp</b>
! 	/^virtual\.domain$/		whatever
! 	/^(.*\)@virtual\.domain$/	joe+$1
! </pre>
  
  <p>
  
+ Notes:
+ 
  <ul>
  
! <li> Be sure to specify the <b>^</b> and <b>\</b> and <b>$</b> or
! else you may have false hits.
  
! <li> Maps with regular expressions are searched sequentially. This
! can be expensive when you list many domains in regular expression
! maps.
  
! <li> Postfix has <b>regexp </b> map support only on modern UNIXes.
! Instead of <b>regexp </b> maps your Postfix system may also support
! <b>pcre</b> maps which have a similar syntax. To find out what maps
! your system supports, use the command <b>postconf -m</b>.
  
  </ul>
  
  <hr>
  
  <a name="masquerade"><h3>Address masquerading with exceptions</h3></a>
***************
*** 1768,1774 ****
  
  This example specifies a command that delivers all local mail to
  mailbox.  See the sample <b>main.cf</b> file for examples. In
! <b>/etc/aliases</i>, you must specify an alias for <b>root</b> that
  directs mail to a real person, otherwise mail sent to <b>root</b>
  will not work as expected.
  
--- 1841,1847 ----
  
  This example specifies a command that delivers all local mail to
  mailbox.  See the sample <b>main.cf</b> file for examples. In
! <b>/etc/aliases</b>, you must specify an alias for <b>root</b> that
  directs mail to a real person, otherwise mail sent to <b>root</b>
  will not work as expected.
  
***************
*** 1801,1807 ****
  
  <li>You need an <b>rmail</b> program that extracts the sender
  address from mail that arrives via UUCP, and that feeds the mail
! into the Postfix <b>sendmail<b> command.  Most UNIX systems come
  with an <b>rmail</b> utility. If you're in a pinch, try the one
  bundled with the Postfix source code in the <b>auxiliary</b>
  directory. Some day Postfix may have its own <b>rmail</b> command.
--- 1874,1880 ----
  
  <li>You need an <b>rmail</b> program that extracts the sender
  address from mail that arrives via UUCP, and that feeds the mail
! into the Postfix <b>sendmail</b> command.  Most UNIX systems come
  with an <b>rmail</b> utility. If you're in a pinch, try the one
  bundled with the Postfix source code in the <b>auxiliary</b>
  directory. Some day Postfix may have its own <b>rmail</b> command.
diff -cr /tmp/postfix-19991231/smtpd/smtpd_check.c ./smtpd/smtpd_check.c
*** /tmp/postfix-19991231/smtpd/smtpd_check.c	Wed Dec 29 21:30:30 1999
--- ./smtpd/smtpd_check.c	Sun Jan  2 16:52:43 2000
***************
*** 1949,1954 ****
--- 1949,1966 ----
  #define NOP ((char **) 0)
  
      if (resolve_local(domain)) {
+ 	if (*var_virtual_maps
+ 	    && maps_find(virtual_maps, domain, 0)) {
+ 	    msg_warn("virtual domain \"%s\" is listed in $mydestination",
+ 		     domain);
+ 	    msg_warn("the $local_recipient_maps feature requires that no");
+ 	    msg_warn("virtual domains are listed in $mydestination");
+ 	    msg_warn("be sure to specify the required \"%s whatever\"",
+ 		     domain);
+ 	    msg_warn("entry in the virtual map, as explained in the man");
+ 	    msg_warn("page and in the FAQ entry for virtual domains");
+ 	    SMTPD_CHECK_RCPT_RETURN(0);
+ 	}
  	if (*var_local_rcpt_maps
  	    && !mail_addr_find(rcpt_canon_maps, STR(reply.recipient), NOP)
  	    && !mail_addr_find(canonical_maps, STR(reply.recipient), NOP)