summaryrefslogtreecommitdiffstats
path: root/README_FILES/COMPATIBILITY_README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README_FILES/COMPATIBILITY_README399
1 files changed, 399 insertions, 0 deletions
diff --git a/README_FILES/COMPATIBILITY_README b/README_FILES/COMPATIBILITY_README
new file mode 100644
index 0000000..55182b7
--- /dev/null
+++ b/README_FILES/COMPATIBILITY_README
@@ -0,0 +1,399 @@
+PPoossttffiixx BBaacckkwwaarrddss--CCoommppaattiibbiilliittyy SSaaffeettyy NNeett
+
+-------------------------------------------------------------------------------
+
+PPuurrppoossee ooff tthhiiss ddooccuummeenntt
+
+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.
+
+This document provides information on the following topics:
+
+ * Detailed descriptions of Postfix backwards-compatibility warnings.
+
+ * What backwards-compatible settings you may have to make permanent in
+ main.cf or master.cf.
+
+ * How to turn off Postfix backwards-compatibility warnings.
+
+OOvveerrvviieeww
+
+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
+turning off the backwards-compatibility safety net as described at the end of
+this document.
+
+Logged with compatibility_level < 1:
+
+ * Using backwards-compatible default setting append_dot_mydomain=yes
+
+ * Using backwards-compatible default setting chroot=y
+
+Logged with compatibility_level < 2:
+
+ * Using backwards-compatible default setting "smtpd_relay_restrictions =
+ (empty)"
+
+ * Using backwards-compatible default setting mynetworks_style=subnet
+
+ * Using backwards-compatible default setting relay_domains=$mydestination
+
+ * Using backwards-compatible default setting smtputf8_enable=no
+
+Logged with compatibility_level < 3.6:
+
+ * Using backwards-compatible default setting smtpd_tls_fingerprint_digest=md5
+
+ * Using backwards-compatible default setting smtp_tls_fingerprint_digest=md5
+
+ * Using backwards-compatible default setting lmtp_tls_fingerprint_digest=md5
+
+ * Using backwards-compatible default setting
+ smtpd_relay_before_recipient_restrictions=no
+
+ * Using backwards-compatible default setting respectful_logging=no
+
+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.
+
+When no more backwards-compatible settings need to be made permanent, the
+system administrator should turn off the backwards-compatibility safety net as
+described at the end of this document.
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg aappppeenndd__ddoott__mmyyddoommaaiinn==yyeess
+
+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.
+
+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:
+
+ * Messages about missing "localhost" in mydestination or other address class:
+
+ 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
+
+ If Postfix logs the above message, add "localhost" to mydestination (or
+ virtual_alias_domains, virtual_mailbox_domains, or relay_domains) and
+ execute the command "ppoossttffiixx rreellooaadd".
+
+ * Messages about incomplete domains in email addresses:
+
+ postfix/trivial-rewrite[25835]: using backwards-compatible
+ default setting append_dot_mydomain=yes to rewrite "foo" to
+ "foo.example.com"
+
+ 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:
+
+ # ppoossttccoonnff aappppeenndd__ddoott__mmyyddoommaaiinn==yyeess
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg cchhrroooott==yy
+
+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.
+
+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:
+
+ postfix/master[27664]: /etc/postfix/master.cf: line 72: using
+ backwards-compatible default setting chroot=y
+
+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:
+
+ # ppoossttccoonnff --FF ssmmttpp//iinneett//cchhrroooott==yy
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg ssmmttppdd__rreellaayy__rreessttrriiccttiioonnss == ((eemmppttyy))
+
+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.
+
+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.
+
+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:
+
+ 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]"
+
+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:
+
+ # ppoossttccoonnff ssmmttppdd__rreellaayy__rreessttrriiccttiioonnss==
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg mmyynneettwwoorrkkss__ssttyyllee==ssuubbnneett
+
+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.
+
+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:
+
+ postfix/smtpd[17375]: using backwards-compatible default setting
+ mynetworks_style=subnet to permit request from client
+ "foo.example.com[10.1.1.1]"
+
+ postfix/postscreen[24982]: using backwards-compatible default
+ setting mynetworks_style=subnet to permit request from client
+ "10.1.1.1"
+
+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:
+
+ # ppoossttccoonnff mmyynneettwwoorrkkss__ssttyyllee==ssuubbnneett
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg rreellaayy__ddoommaaiinnss==$$mmyyddeessttiinnaattiioonn
+
+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.
+
+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.
+
+ * Messages about accepting mail for a remote domain:
+
+ postfix/smtpd[19052]: using backwards-compatible default setting
+ relay_domains=$mydestination to accept mail for domain
+ "foo.example.com"
+
+ postfix/smtpd[19052]: using backwards-compatible default setting
+ relay_domains=$mydestination to accept mail for address
+ "user@foo.example.com"
+
+ * Messages about providing ETRN service for a remote domain:
+
+ postfix/smtpd[19138]: using backwards-compatible default setting
+ relay_domains=$mydestination to flush mail for domain
+ "bar.example.com"
+
+ postfix/smtp[13945]: using backwards-compatible default setting
+ relay_domains=$mydestination to update fast-flush logfile for
+ domain "bar.example.com"
+
+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:
+
+ # ppoossttccoonnff ''rreellaayy__ddoommaaiinnss==$$mmyyddeessttiinnaattiioonn''
+ # ppoossttffiixx rreellooaadd
+
+Note: quotes are required as indicated above.
+
+Instead of $mydestination, it may be better to specify an explicit list of
+domain names.
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg ssmmttppuuttff88__eennaabbllee==nnoo
+
+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.
+
+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:
+
+ 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]
+
+ 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]
+
+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:
+
+ # ppoossttccoonnff ssmmttppuuttff88__eennaabbllee==nnoo
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg ssmmttppdd__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt==mmdd55
+
+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.
+
+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.
+
+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:
+
+ postfix/smtpd[27560]: using backwards-compatible default setting
+ smtpd_tls_fingerprint_digest=md5 to compute certificate fingerprints
+
+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.
+
+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
+update your compatibility level.
+
+ # ppoossttccoonnff ssmmttppdd__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt==mmdd55
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg ssmmttpp__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt==mmdd55
+
+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.
+
+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.
+
+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:
+
+ postfix/smtp[27560]: using backwards-compatible default setting
+ smtp_tls_fingerprint_digest=md5 to compute certificate fingerprints
+
+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
+update your compatibility level.
+
+ # ppoossttccoonnff ''ssmmttpp__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt == mmdd55'' \\
+ ''llmmttpp__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt == mmdd55''
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg
+ssmmttppdd__rreellaayy__bbeeffoorree__rreecciippiieenntt__rreessttrriiccttiioonnss==nnoo
+
+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.
+
+ 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.
+
+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:
+
+ 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]"
+
+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:
+
+ # ppoossttccoonnff ssmmttppdd__rreellaayy__bbeeffoorree__rreecciippiieenntt__rreessttrriiccttiioonnss==nnoo
+ # ppoossttffiixx rreellooaadd
+
+UUssiinngg bbaacckkwwaarrddss--ccoommppaattiibbllee ddeeffaauulltt sseettttiinngg rreessppeeccttffuull__llooggggiinngg==nnoo
+
+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.
+
+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:
+
+ postfix/postscreen[22642]: Using backwards-compatible default setting
+ respectful_logging=no for client [address]:port
+
+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.
+
+ # ppoossttccoonnff ""rreessppeeccttffuull__llooggggiinngg == nnoo""
+ # ppoossttffiixx rreellooaadd
+
+TTuurrnniinngg ooffff tthhee bbaacckkwwaarrddss--ccoommppaattiibbiilliittyy ssaaffeettyy nneett
+
+Backwards compatibility is turned off by updating the compatibility_level
+setting in main.cf.
+
+ # ppoossttccoonnff ccoommppaattiibbiilliittyy__lleevveell==NN
+ # ppoossttffiixx rreellooaadd
+
+For N specify the number that is logged in your postfix(1) warning message:
+
+ warning: To disable backwards compatibility use "postconf
+ compatibility_level=N" and "postfix reload"
+
+Sites that don't care about backwards compatibility may set
+"compatibility_level = 9999" at their own risk.
+
+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 major.minor.patch, where patch is usually omitted and
+defaults to zero. Earlier compatibility levels are 0, 1 and 2.
+
+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.
+