diff options
Diffstat (limited to '')
| -rw-r--r-- | proto/COMPATIBILITY_README.html | 594 |
1 files changed, 594 insertions, 0 deletions
diff --git a/proto/COMPATIBILITY_README.html b/proto/COMPATIBILITY_README.html new file mode 100644 index 0000000..7020dbe --- /dev/null +++ b/proto/COMPATIBILITY_README.html @@ -0,0 +1,594 @@ +<!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=utf-8"> + +</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 main.cf or master.cf. </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> Logged with compatibility_level < 1: </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> + +</ul> + +<p> Logged with compatibility_level < 2: </p> + +<ul> + +<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> Logged with compatibility_level < 3.6: </p> + +<ul> + +<li> <p> <a href="#smtpd_digest"> Using backwards-compatible +default setting smtpd_tls_fingerprint_digest=md5</a> </p> + +<li> <p> <a href="#smtp_digest"> Using backwards-compatible +default setting smtp_tls_fingerprint_digest=md5</a> </p> + +<li> <p> <a href="#smtp_digest"> Using backwards-compatible +default setting lmtp_tls_fingerprint_digest=md5</a> </p> + +<li> <p> <a href="#relay_before_rcpt"> Using backwards-compatible +default setting smtpd_relay_before_recipient_restrictions=no</a> </p> + +<li> <p> <a href="#respectful_logging"> Using backwards-compatible +default setting respectful_logging=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 main.cf or master.cf, 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 append_dot_mydomain 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 append_dot_mydomain parameter is left at +its implicit default value, and the compatibility_level setting is +less than 1, Postfix may log one of the following messages:</p> + +<ul> + +<li> <p> Messages about missing "localhost" in mydestination or +other address class: </p> + +<blockquote> +<pre> +postfix/trivial-rewrite[14777]: using backwards-compatible + default setting append_dot_mydomain=yes to rewrite + "localhost" to "localhost.example.com"; please add + "localhost" to mydestination or other address class +</pre> +</blockquote> + +<p> If Postfix logs the above message, add "localhost" to +mydestination (or virtual_alias_domains, virtual_mailbox_domains, +or relay_domains) 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 append_dot_mydomain=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 "append_dot_mydomain = yes" permanent +in main.cf: </p> + +<blockquote> +<pre> +# <b>postconf append_dot_mydomain=yes</b> +# <b>postfix reload</b> +</pre> +</blockquote> + +</ul> + +<h2> <a name="chroot"> Using backwards-compatible default +setting chroot=y</a> </h2> + +<p> The master.cf 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 master.cf chroot field is left at its +implicit default value, and the compatibility_level setting +is less than 1, Postfix may log the following message while it +reads the master.cf file: </p> + +<blockquote> +<pre> +postfix/master[27664]: /etc/postfix/master.cf: 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 master.cf. 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 smtpd_relay_restrictions feature was introduced with Postfix +version 2.10, as a safety mechanism for configuration errors in +smtpd_recipient_restrictions that could make Postfix an open relay. +</p> + +<p> The smtpd_relay_restrictions implicit default setting forbids +mail to remote destinations from clients that don't match +permit_mynetworks or permit_sasl_authenticated. 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 compatibility_level less than 1, and the +smtpd_relay_restrictions 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 + "smtpd_relay_restrictions = (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 +"smtpd_relay_restrictions=" (i.e. empty) permanent in main.cf: + +<blockquote> +<pre> +# <b>postconf smtpd_relay_restrictions=</b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<h2> <a name="mynetworks_style"> Using backwards-compatible default +setting mynetworks_style=subnet</a> </h2> + +<p> The mynetworks_style default value has changed from "subnet" +to "host". This parameter is used to implement the "permit_mynetworks" +feature. The change could cause 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 mynetworks and mynetworks_style parameters are +left at their implicit default values, and the compatibility_level +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 + mynetworks_style=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 mynetworks_style=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 +"mynetworks_style = subnet" permanent in main.cf: </p> + +<blockquote> +<pre> +# <b>postconf mynetworks_style=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 relay_domains default value has changed from "$mydestination" +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 relay_domains parameter is left at its implicit +default value, and the compatibility_level 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 + relay_domains=$mydestination to accept mail for domain + "foo.example.com" +</pre> +</blockquote> + +<blockquote> +<pre> +postfix/smtpd[19052]: using backwards-compatible default setting + relay_domains=$mydestination 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 + relay_domains=$mydestination to flush mail for domain + "bar.example.com" +</pre> +</blockquote> + +<blockquote> +<pre> +postfix/smtp[13945]: using backwards-compatible default setting + relay_domains=$mydestination 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 +"relay_domains = $mydestination" permanent in main.cf: </p> + +<blockquote> +<pre> +# <b>postconf 'relay_domains=$mydestination'</b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<p> Note: quotes are required as indicated above. </p> + +<p> Instead of $mydestination, 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 smtputf8_enable 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 smtputf8_enable parameter is left at its implicit +default value, and the compatibility_level 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 + smtputf8_enable=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 + smtputf8_enable=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 "smtputf8_enable = no" permanent +in main.cf: + +<blockquote> +<pre> +# <b>postconf smtputf8_enable=no</b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<h2> <a name="smtpd_digest"> Using backwards-compatible +default setting smtpd_tls_fingerprint_digest=md5</a> </h2> + +<p> The smtpd_tls_fingerprint_digest default value has changed from +"md5" to "sha256". With the new "sha256" setting, the Postfix SMTP +server avoids using the deprecated "md5" algorithm and computes a more +secure digest of the client certificate. </p> + +<p> If you're using the default "md5" setting, or even an explicit +"sha1" (also deprecated) setting, you should consider switching to +"sha256". This will require updating any associated lookup table keys +with the "sha256" digests of the expected client certificate or public +key. </p> + +<p> As long as the smtpd_tls_fingerprint_digest parameter is left at its +implicit default value, and the compatibility_level setting is less than +3.6, Postfix logs a warning each time a client certificate or public key +fingerprint is (potentially) used for access control: </p> + +<blockquote> +<pre> +postfix/smtpd[27560]: using backwards-compatible default setting + smtpd_tls_fingerprint_digest=md5 to compute certificate fingerprints +</pre> +</blockquote> + +<p> Since any client certificate fingerprints are passed in policy service +lookups, and Postfix doesn't know whether the fingerprint will be used, the +warning may also be logged when policy lookups are performed for connections +that used a client certificate, even if the policy service does not in fact +examine the client certificate. To reduce the noise somewhat, such warnings +are issued at most once per smtpd(8) process instance. </p> + +<p> If you prefer to stick with "md5", you can suppress the warnings by +making that setting explicit. After addressing any other compatibility +warnings, you can <a href="#turnoff">update</a> your compatibility level. +</p> + +<blockquote> +<pre> +# <b>postconf smtpd_tls_fingerprint_digest=md5</b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<h2> <a name="smtp_digest"> Using backwards-compatible +default setting smtp_tls_fingerprint_digest=md5</a> </h2> + +<p> The smtp_tls_fingerprint_digest and lmtp_tls_fingerprint_digest +default values have changed from "md5" to "sha256". With the new +"sha256" setting, the Postfix SMTP and LMTP client avoids using the +deprecated "md5" algorithm and computes a more secure digest of the +server certificate. </p> + +<p> If you're using the default "md5" setting, or even an explicit +"sha1" (also deprecated) setting, you should consider switching to +"sha256". This will require updating any "fingerprint" security level +policies in the TLS policy table to specify matching "sha256" digests of +the expected server certificates or public keys. </p> + +<p> As long as the smtp_tls_fingerprint_digest (or LMTP equivalent) +parameter is left at its implicit default value, and the +compatibility_level setting is less than 3.6, Postfix logs a warning each +time the "fingerprint" security level is used to specify matching "md5" +digests of trusted server certificates or public keys: </p> + +<blockquote> +<pre> +postfix/smtp[27560]: using backwards-compatible default setting + smtp_tls_fingerprint_digest=md5 to compute certificate fingerprints +</pre> +</blockquote> + +<p> If you prefer to stick with "md5", you can suppress the warnings by +making that setting explicit. After addressing any other compatibility +warnings, you can <a href="#turnoff">update</a> your compatibility level. +</p> + +<blockquote> +<pre> +# <b>postconf 'smtp_tls_fingerprint_digest = md5' \ + 'lmtp_tls_fingerprint_digest = md5' </b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<h2> <a name="relay_before_rcpt"> Using backwards-compatible +default setting smtpd_relay_before_recipient_restrictions=no</a> </h2> + +<p> The smtpd_relay_before_recipient_restrictions feature was +introduced in Postfix version 3.6, to evaluate smtpd_relay_restrictions +before smtpd_recipient_restrictions. Historically, smtpd_relay_restrictions +was evaluated after smtpd_recipient_restrictions, contradicting +documented behavior. </p> + +<blockquote> <p> Background: smtpd_relay_restrictions is +primarily designed to enforce a mail relaying policy, while +smtpd_recipient_restrictions is primarily designed to enforce spam +blocking policy. Both are evaluated while replying to the RCPT TO +command, and both support the same features. </p> </blockquote> + +<p> To maintain compatibility with earlier versions, Postfix will +keep evaluating smtpd_recipient_restrictions before +smtpd_relay_restrictions, as long as the compatibility_level is +less than 3.6, and the smtpd_relay_before_recipient_restrictions +parameter is left at its implicit default setting. As a reminder, +Postfix may log the following message: </p> + +<blockquote> +<pre> +postfix/smtpd[54696]: using backwards-compatible default setting + smtpd_relay_before_recipient_restrictions=no to reject recipient + "user@example.com" from client "host.example.net[10.0.0.2]" +</pre> +</blockquote> + +<p> If Postfix should keep evaluating smtpd_recipient_restrictions +before smtpd_relay_restrictions, then the system +administrator should make the backwards-compatible setting +"smtpd_relay_before_recipient_restrictions=no" permanent in main.cf: </p> + +<blockquote> +<pre> +# <b> postconf smtpd_relay_before_recipient_restrictions=no </b> +# <b> postfix reload </b> +</pre> +</blockquote> + +<h2> <a name="respectful_logging"> Using backwards-compatible +default setting respectful_logging=no</a> </h2> + +<p> Postfix version 3.6 deprecates configuration parameter names and +logging that suggest white is better than black. Instead it prefers +'allowlist, 'denylist', and variations of those words. While the renamed +configuration parameters have backwards-compatible default values, +the changes in logging could affect logfile analysis tools. </p> + +<p> To avoid breaking existing logfile analysis tools, Postfix will keep +logging the deprecated form, as long as the respectful_logging parameter +is left at its implicit default value, and the compatibility_level +setting is less than 3.6. As a reminder, Postfix may log the following +when a remote SMTP client is allowlisted or denylisted: </p> + +<blockquote> +<pre> +postfix/postscreen[22642]: Using backwards-compatible default setting + respectful_logging=no for client [<i>address</i>]:<i>port</i> +</pre> +</blockquote> + +<p> If Postfix should keep logging the deprecated form, then the +system administrator should make the backwards-compatible setting +"respectful_logging = no" permanent in main.cf. + +<blockquote> +<pre> +# <b>postconf "respectful_logging = 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 +compatibility_level setting in main.cf. </p> + +<blockquote> +<pre> +# <b>postconf compatibility_level=<i>N</i></b> +# <b>postfix reload</b> +</pre> +</blockquote> + +<p> For <i>N</i> specify the number that is logged in your postfix(1) +warning message: </p> + +<blockquote> +<pre> +warning: To disable backwards compatibility use "postconf compatibility_level=<i>N</i>" and "postfix reload" +</pre> +</blockquote> + +<p> Sites that don't care about backwards compatibility may set +"compatibility_level = 9999" at their own risk. </p> + +<p> Starting with Postfix version 3.6, the compatibility level in +the above warning message is the Postfix version that introduced +the last incompatible change. The level is formatted as +<i>major.minor.patch</i>, where <i>patch</i> is usually omitted and +defaults to zero. Earlier compatibility levels are 0, 1 and 2. </p> + +<p> NOTE: Postfix 3.6 also introduces support for the "<level", +"<=level", and other operators to compare compatibility levels. +With the standard operators "<", "<=", etc., compatibility +level "3.10" would be smaller than "3.9" which is undesirable. </p> + +</body> + +</html> |