1 files changed, 395 insertions, 0 deletions
diff --git a/html/COMPATIBILITY_README.html b/html/COMPATIBILITY_README.html
new file mode 100644
index 0000000..d527e19
--- /dev/null
+++ b/html/COMPATIBILITY_README.html
@@ -0,0 +1,395 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+
+<head>
+
+<title>Postfix Backwards-Compatibility Safety Net</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
+Backwards-Compatibility Safety Net</h1>
+
+<hr>
+
+<h2>Purpose of this document </h2>
+
+<p> Postfix 3.0 introduces a safety net that runs Postfix programs
+with backwards-compatible default settings after an upgrade. The
+safety net will log a warning whenever a "new" default setting could
+have an negative effect on your mail flow. </p>
+
+<p>This document provides information on the following topics: </p>
+
+<ul>
+
+<li> <p> <a href="#overview">Detailed descriptions</a> of Postfix
+backwards-compatibility warnings.
+
+<li> <p> What backwards-compatible settings you may have to make
+permanent in <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a>.  </p>
+
+<li> <p> <a href="#turnoff">How to turn off</a> Postfix
+backwards-compatibility warnings. </p>
+
+</ul>
+
+<h2> <a name="overview"> Overview </a> </h2>
+
+<p>  With backwards compatibility turned on, Postfix logs a message
+whenever a backwards-compatible default setting may be required for
+continuity of service.  Based on this logging the system administrator
+can decide if any backwards-compatible settings need to be made
+permanent in main.cf or master.cf, before <a href="#turnoff">turning
+off the backwards-compatibility safety net</a> as described at the
+end of this document. </p>
+
+<p> The following messages may be logged: </p>
+
+<ul>
+
+<li> <p> <a href="#append_dot_mydomain"> Using backwards-compatible
+default setting append_dot_mydomain=yes </a> </p>
+
+<li> <p> <a href="#chroot"> Using backwards-compatible default setting
+chroot=y</a> </p>
+
+<li><p> <a href="#relay_restrictions"> Using backwards-compatible
+default setting smtpd_relay_restrictions = (empty)</a> </p>
+
+<li> <p> <a href="#mynetworks_style"> Using backwards-compatible
+default setting mynetworks_style=subnet </a> </p>
+
+<li> <p> <a href="#relay_domains"> Using backwards-compatible default
+setting relay_domains=$mydestination </a> </p>
+
+<li> <p> <a href="#smtputf8_enable"> Using backwards-compatible
+default setting smtputf8_enable=no</a> </p>
+
+</ul>
+
+<p> If such a message is logged in the context of a legitimate
+request, the system administrator should make the backwards-compatible
+setting permanent in <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a>, as detailed in the
+sections that follow. </p>
+
+<p> When no more backwards-compatible settings need to be made
+permanent, the system administrator should <a href="#turnoff">turn
+off the backwards-compatibility safety net</a> as described at the
+end of this document. </p>
+
+<h2> <a name="append_dot_mydomain"> Using backwards-compatible default
+setting append_dot_mydomain=yes</a> </h2>
+
+<p> The <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> default value has changed from "yes"
+to "no". This could result in unexpected non-delivery of email after
+Postfix is updated from an older version. The backwards-compatibility
+safety net is designed to prevent such surprises. </p>
+
+<p> As long as the <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> parameter is left at
+its implicit default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is
+less than 1, Postfix may log one of the following messages:</p>
+
+<ul>
+
+<li> <p> Messages about missing "localhost" in <a href="postconf.5.html#mydestination">mydestination</a> or
+other address class: </p>
+
+<blockquote>
+<pre>
+postfix/trivial-rewrite[14777]: using backwards-compatible
+    default setting <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes to rewrite
+    "localhost" to "localhost.example.com"; please add
+    "localhost" to <a href="postconf.5.html#mydestination">mydestination</a> or other address class
+</pre>
+</blockquote>
+
+<p> If Postfix logs the above message, add "localhost" to
+<a href="postconf.5.html#mydestination">mydestination</a> (or <a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a>, <a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>,
+or <a href="postconf.5.html#relay_domains">relay_domains</a>) and execute the command "<b>postfix reload</b>".
+
+<li> <p> Messages about incomplete domains in email addresses: </p>
+
+<blockquote>
+<pre>
+postfix/trivial-rewrite[25835]: using backwards-compatible
+    default setting <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes to rewrite "foo" to
+    "foo.example.com"
+</pre>
+</blockquote>
+
+<p> If Postfix logs the above message for domains different from
+"localhost", and the sender cannot be changed to use complete domain
+names in email addresses, then the system administrator should make
+the backwards-compatible setting "<a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> = yes" permanent
+in <a href="postconf.5.html">main.cf</a>: </p>
+
+<blockquote>
+<pre>
+# <b>postconf <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+</ul>
+
+<h2> <a name="chroot"> Using backwards-compatible default
+setting chroot=y</a> </h2>
+
+<p> The <a href="master.5.html">master.cf</a> chroot default value has changed from "y" (yes)
+to "n" (no). The new default avoids the need for copies of system
+files under the Postfix queue directory. However, sites with strict
+security requirements may want to keep the chroot feature enabled
+after updating Postfix from an older version. The backwards-compatibility
+safety net is designed allow the administrator to choose if they
+want to keep the old behavior. </p>
+
+<p> As long as a <a href="master.5.html">master.cf</a> chroot field is left at its
+implicit default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting
+is less than 1, Postfix may log the following message while it
+reads the <a href="master.5.html">master.cf</a> file: </p>
+
+<blockquote>
+<pre>
+postfix/master[27664]: /etc/postfix/<a href="master.5.html">master.cf</a>: line 72: using
+    backwards-compatible default setting chroot=y
+</pre>
+</blockquote>
+
+<p> If this service should remain chrooted, then the system
+administrator should make the backwards-compatible setting "chroot
+= y" permanent in <a href="master.5.html">master.cf</a>.  For example, to update the chroot
+setting for the "smtp inet" service: </p>
+
+<blockquote>
+<pre>
+# <b>postconf -F smtp/inet/chroot=y</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<h2> <a name="relay_restrictions"> Using backwards-compatible default
+setting smtpd_relay_restrictions = (empty)</a> </h2>
+
+<p> The <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> feature was introduced with Postfix
+version 2.10, as a safety mechanism for configuration errors in
+<a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> that could make Postfix an open relay.
+</p>
+
+<p> The <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> implicit default setting forbids
+mail to remote destinations from clients that don't match
+<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> or <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>. This could result
+in unexpected 'Relay access denied' errors after Postfix is updated
+from an older Postfix version. The backwards-compatibility safety
+net is designed to prevent such surprises. </p>
+
+<p> When the <a href="postconf.5.html#compatibility_level">compatibility_level</a> less than 1, and the
+<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> parameter is left at its implicit default
+setting, Postfix may log the following message: </p>
+
+<blockquote>
+<pre>
+postfix/smtpd[38463]: using backwards-compatible default setting
+    "<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> = (empty)" to avoid "Relay access
+    denied" error for recipient "user@example.com" from client
+    "host.example.net[10.0.0.2]"
+</pre>
+</blockquote>
+
+<p> If this request should not be blocked, then the system
+administrator should make the backwards-compatible setting
+"<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=" (i.e. empty) permanent in <a href="postconf.5.html">main.cf</a>:
+
+<blockquote>
+<pre>
+# <b>postconf <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<h2> <a name="mynetworks_style"> Using backwards-compatible default
+setting mynetworks_style=subnet</a> </h2>
+
+<p> The <a href="postconf.5.html#mynetworks_style">mynetworks_style</a> default value has changed from "subnet"
+to "host". This parameter is used to implement the "<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>"
+feature. The change could in unexpected 'access denied' errors after
+Postfix is updated from an older version. The backwards-compatibility
+safety net is designed to prevent such surprises. </p>
+
+<p> As long as the <a href="postconf.5.html#mynetworks">mynetworks</a> and <a href="postconf.5.html#mynetworks_style">mynetworks_style</a> parameters are
+left at their implicit default values, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a>
+setting is less than 2, the Postfix SMTP server may log one of the
+following messages: </p>
+
+<blockquote>
+<pre>
+postfix/smtpd[17375]: using backwards-compatible default setting
+    <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet to permit request from client
+    "foo.example.com[10.1.1.1]"
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+postfix/postscreen[24982]: using backwards-compatible default
+    setting <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet to permit request from client
+    "10.1.1.1"
+</pre>
+</blockquote>
+
+<p> If the client request should not be rejected, then the system
+administrator should make the backwards-compatible setting
+"<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = subnet" permanent in <a href="postconf.5.html">main.cf</a>: </p>
+
+<blockquote>
+<pre>
+# <b>postconf <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<h2><a name="relay_domains"> Using backwards-compatible default
+setting relay_domains=$mydestination </a> </h2>
+
+<p> The <a href="postconf.5.html#relay_domains">relay_domains</a> default value has changed from "$<a href="postconf.5.html#mydestination">mydestination</a>"
+to the empty value. This could result in unexpected 'Relay access
+denied' errors or ETRN errors after Postfix is updated from an older
+version. The backwards-compatibility safety net is designed to
+prevent such surprises. </p>
+
+<p> As long as the <a href="postconf.5.html#relay_domains">relay_domains</a> parameter is left at its implicit
+default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is less than 2,
+Postfix may log one of the following messages.  </p>
+
+<ul>
+
+<li> <p> Messages about accepting mail for a remote domain:</p>
+
+<blockquote>
+<pre>
+postfix/smtpd[19052]: using backwards-compatible default setting
+    <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to accept mail for domain
+    "foo.example.com"
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+postfix/smtpd[19052]: using backwards-compatible default setting
+    <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to accept mail for address
+    "user@foo.example.com"
+</pre>
+</blockquote>
+
+<li> <p> Messages about providing ETRN service for a remote domain:</p>
+
+<blockquote>
+<pre>
+postfix/smtpd[19138]: using backwards-compatible default setting
+    <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to flush mail for domain
+    "bar.example.com"
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+postfix/smtp[13945]: using backwards-compatible default setting
+    <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to update fast-flush logfile for
+    domain "bar.example.com"
+</pre>
+</blockquote>
+
+</ul>
+
+<p> If Postfix should continue to accept mail for that domain or
+continue to provide ETRN service for that domain, then the system
+administrator should make the backwards-compatible setting
+"<a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydestination">mydestination</a>" permanent in <a href="postconf.5.html">main.cf</a>: </p>
+
+<blockquote>
+<pre>
+# <b>postconf '<a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a>'</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<p> Note: quotes are required as indicated above. </p>
+
+<p> Instead of $<a href="postconf.5.html#mydestination">mydestination</a>, it may be better to specify an
+explicit list of domain names. </p>
+
+<h2> <a name="smtputf8_enable"> Using backwards-compatible default
+setting smtputf8_enable=no</a> </h2>
+
+<p> The <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> default value has changed from "no" to "yes.
+With the new "yes" setting, the Postfix SMTP server rejects non-ASCII
+addresses from clients that don't request SMTPUTF8 support, after
+Postfix is updated from an older version. The backwards-compatibility
+safety net is designed to prevent such surprises. </p>
+
+<p> As long as the <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> parameter is left at its implicit
+default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is
+less than 1, Postfix logs a warning each time an SMTP command uses a
+non-ASCII address localpart without requesting SMTPUTF8 support: </p>
+
+<blockquote>
+<pre>
+postfix/smtpd[27560]: using backwards-compatible default setting
+    <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no to accept non-ASCII sender address
+    "??@example.org" from localhost[127.0.0.1]
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+postfix/smtpd[27560]: using backwards-compatible default setting
+    <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no to accept non-ASCII recipient address
+    "??@example.com" from localhost[127.0.0.1]
+</pre>
+</blockquote>
+
+<p> If the address should not be rejected, and the client cannot
+be updated to use SMTPUTF8, then the system administrator should
+make the backwards-compatible setting "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = no" permanent
+in <a href="postconf.5.html">main.cf</a>:
+
+<blockquote>
+<pre>
+# <b>postconf <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no</b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<h2> <a name="turnoff">Turning off the backwards-compatibility safety net</a> </h2>
+
+<p> Backwards compatibility is turned off by updating the
+<a href="postconf.5.html#compatibility_level">compatibility_level</a> setting in <a href="postconf.5.html">main.cf</a>. </p>
+
+<blockquote>
+<pre>
+# <b>postconf <a href="postconf.5.html#compatibility_level">compatibility_level</a>=<i>N</i></b>
+# <b>postfix reload</b>
+</pre>
+</blockquote>
+
+<p> For <i>N</i> specify the number that is logged in your <a href="postfix.1.html">postfix(1)</a>
+warning message: </p>
+
+<blockquote>
+<pre>
+warning: To disable backwards compatibility use "postconf <a href="postconf.5.html#compatibility_level">compatibility_level</a>=<i>N</i>" and "postfix reload"
+</pre>
+</blockquote>
+
+<p> Sites that don't care about backwards compatibility may set
+"<a href="postconf.5.html#compatibility_level">compatibility_level</a> = 9999" at their own risk. </p>
+
+</body>
+
+</html>