# Postfix Backwards-Compatibility Safety Net

## Purpose of this document

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.

## Overview

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

- Using backwards-compatible default setting "smtpd_relay_restrictions = (empty)"

- Using backwards-compatible default setting smtputf8_enable=no

Logged with compatibility_level < 2:

- Using backwards-compatible default setting mynetworks_style=subnet

- Using backwards-compatible default setting relay_domains=$mydestination

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

Logged with compatibility_level < 3.11:

- using backwards-compatible default setting smtp_tlsrpt_skip_reused_handshakes=yes

- using backwards-compatible default setting xxx_security_level=(empty)

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.

## Using backwards-compatible default setting append_dot_mydomain=yes

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 unspecified 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 "postfix reload".

- 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:

  >     # postconf append_dot_mydomain=yes
  >     # postfix reload

## Using backwards-compatible default setting chroot=y

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 unspecified 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:

>     # postconf -F smtp/inet/chroot=y
>     # postfix reload

## Using backwards-compatible default setting smtpd_relay_restrictions = (empty)

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 unspecified 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:

>     # postconf smtpd_relay_restrictions=
>     # postfix reload

## Using backwards-compatible default setting smtputf8_enable=no

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 unspecified 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:

>     # postconf smtputf8_enable=no
>     # postfix reload

## Using backwards-compatible default setting mynetworks_style=subnet

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 unspecified 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:

>     # postconf mynetworks_style=subnet
>     # postfix reload

## Using backwards-compatible default setting relay_domains=$mydestination

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 unspecified 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:

>     # postconf 'relay_domains=$mydestination'
>     # postfix reload

Note: quotes are required as indicated above.

Instead of $mydestination, it may be better to specify an explicit list of domain names.

## Using backwards-compatible default setting smtpd_tls_fingerprint_digest=md5

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 unspecified 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.

>     # postconf smtpd_tls_fingerprint_digest=md5
>     # postfix reload

## Using backwards-compatible default setting smtp_tls_fingerprint_digest=md5

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 unspecified 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.

>     # postconf 'smtp_tls_fingerprint_digest = md5' \
>         'lmtp_tls_fingerprint_digest = md5'
>     # postfix reload

## Using backwards-compatible default setting smtpd_relay_before_recipient_restrictions=no

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 unspecified 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:

>     #  postconf smtpd_relay_before_recipient_restrictions=no
>     #  postfix reload

## Using backwards-compatible default setting respectful_logging=no

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 unspecified 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.

>     # postconf "respectful_logging = no"
>     # postfix reload

## Using backwards-compatible default setting smtp_tlsrpt_skip_reused_handshakes=yes

Postfix version 3.11 changes the default value for smtp_tlsrpt_skip_reused_handshakes from "yes" to "no". The backwards-compatibility safety net is designed to prevent an unexpected change in reporting behavior when Postfix is updated from an older version.

As long as the smtp_tlsrpt_skip_reused_handshakes parameter is left unspecified at its implicit default value, and the compatibility_level setting is less than 3.11, Postfix will log a reminder that it is using the backwards-compatible default:

>     postfix/smtp[388157] using backwards-compatible default setting
>         smtp_tlsrpt_skip_reused_handshakes=yes

To keep the old default setting, the system administrator should make the backwards-compatible setting "smtp_tlsrpt_skip_reused_handshakes = yes" permanent in main.cf:

>     # postconf smtp_tlsrpt_skip_reused_handshakes=yes
>     # postfix reload

## Using backwards-compatible default setting xxx_security_level=(empty)

When built with TLS support, Postfix version 3.11 changes the default SMTP client TLS security level from "empty" to "may". The backwards-compatibility safety net is designed to prevent an unexpected change in mail sending behavior when Postfix is updated from an older version.

There is no equivalent change for Postfix server TLS security levels, because changing the level alone is not sufficient. Server-side TLS requires that at least one private key and one public-key certificate chain are configured.

As long as a TLS security level parameter is left unspecified at its implicit default value, and the compatibility_level setting is less than 3.11, Postfix will log one of the following reminders that it is using the backwards-compatible default:

>     postfix/smtp[...] using backwards-compatible default setting
>         smtp_tls_security_level=(empty)

>     postfix/tlsproxy[...] using backwards-compatible default setting
>         tlsproxy_client_security_level=(empty)

To keep the old default setting, the system administrator should make the backwards-compatible empty setting permanent in main.cf:

>     # postconf xxx_security_level=
>     # postfix reload

where xxx is taken from the above compatibility message.

## Turning off the backwards-compatibility safety net

Backwards compatibility is turned off by updating the compatibility_level setting in main.cf.

>     # postconf compatibility_level=N
>     # postfix reload

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.