diff options
Diffstat (limited to 'README_FILES/COMPATIBILITY_README')
| -rw-r--r-- | README_FILES/COMPATIBILITY_README | 399 |
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. + |