postfix/dist/RELEASE_NOTES-3.6

This is the Postfix 3.6 (stable) release.

The stable Postfix release is called postfix-3.6.x where 3=major
release number, 6=minor release number, x=patchlevel. The stable
release never changes except for patches that address bugs or
emergencies. Patches change the patchlevel and the release date.

New features are developed in snapshot releases. These are called
postfix-3.7-yyyymmdd where yyyymmdd is the release date (yyyy=year,
mm=month, dd=day). Patches are never issued for snapshot releases;
instead, a new snapshot is released.

The mail_release_date configuration parameter (format: yyyymmdd)
specifies the release date of a stable release or snapshot release.

If you upgrade from Postfix 3.4 or earlier, read RELEASE_NOTES-3.5
before proceeding.

License change
---------------

This software is distributed with a dual license: in addition to the
historical IBM Public License 1.0, it is now also distributed with the
more recent Eclipse Public License 2.0. Recipients can choose to take
the software under the license of their choice. Those who are more
comfortable with the IPL can continue with that license.

Major changes - internal protocol identification
------------------------------------------------

[Incompat 20200920] Internal protocols have changed. You need to
"postfix stop" before updating, or before backing out to an earlier
release, otherwise long-running daemons (pickup, qmgr, verify, tlsproxy,
postscreen) may fail to communicate with the rest of Postfix, causing
mail delivery delays until Postfix is restarted.

This change does not affect message files in Postfix queue directories,
only the communication between running Postfix programs.

With this change, every Postfix internal service, including the postdrop
command, announces the name of its protocol before doing any other I/O.
Every Postfix client program, including the Postfix sendmail command,
will verify that the protocol name matches what it is supposed to be.

The purpose of this change is to produce better error messages, for
example, when someone configures the discard daemon as a bounce
service in master.cf, or vice versa.

This change may break third-party programs that implement a
Postfix-internal protocol such as qpsmtpd. Such programs have never
been supported. Fortunately, this will be an easy fix: look at the
first data from the cleanup daemon: if it is a protocol announcement,
you're talking to Postfix 3.6 or later. That's the only real change.

Major changes - tls
-------------------

[Incompat 20200705] The minimum supported OpenSSL version is 1.1.1,
which will reach the end of life by 2023-09-11. Postfix 3.6 is
expected to reach the end of support in 2025. Until then, Postfix
will be updated as needed for compatibility with OpenSSL.

The default fingerprint digest has changed from md5 to sha256 (Postfix
3.6 with compatibility_level >= 3.6). With a lower compatibility_level
setting, Postfix defaults to using md5, and logs a warning when a Postfix
configuration specifies no explicit digest type.

Export-grade Diffie-Hellman key exchange is no longer supported,
and the tlsproxy_tls_dh512_param_file parameter is ignored,

[Feature 20200906] The tlstype.pl helper script by Viktor Dukhovni
reports TLS information per message delivery. This processes output
from the collate.pl script. See auxiliary/collate/README.tlstype and
auxiliary/collate/tlstype.pl.

Major changes - compatibility level
-----------------------------------

[Feature 20210109] Starting with Postfix version 3.6, the compatibility
level is "3.6". In future Postfix releases, the compatibility level will
be 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.

This also introduces main.cf and master.cf support for the <=level,
<level, and other operators to compare compatibility levels. With the
standard <=, <, etc. operators, compatibility level 3.10 would be less
than 3.9, which is undesirable.

Major changes - services(5) override
------------------------------------

[Feature 20210418] Postfix no longer uses the services(5) database
to look up the TCP ports for SMTP and LMTP services. Instead, this
information is configured with the new known_tcp_ports configuration
parameter (default: lmtp=24, smtp=25, smtps=submissions=465,
submission=587). When a service is not specified in known_tcp_ports,
Postfix will still query the services(5) database.

Major changes - local_login_sender_maps
---------------------------------------

[Feature 20201025] Fine-grained control over the envelope sender address
for submission with the Postfix sendmail (or postdrop) commands.

The local_login_sender_maps parameter (default: static:*) specifies
a list of lookup tables that are searched by the UNIX login name, and
that return a list of allowed envelope sender patterns separated by
space or comma. The default is backwards-compatible: every user may
specify any sender envelope address.

This feature is enforced by the postdrop command. When no UNIX login
name is available, the postdrop command will prepend "uid:" to the
numerical UID and use that instead.

This feature ignores address extensions in the user-specified
envelope sender address.

Besides the special pattern "*" which allows any sender address,
there are "<>" which matches an empty sender address, and the
"@domain" wildcard pattern. More information about those can be found
in the postconf(5) manpage.

Example:

/etc/postfix/main.cf:
    # Allow root and postfix full control, anyone else can only
    # send mail as themselves. Use "uid:" followed by the numerical
    # UID when the UID has no entry in the UNIX password file.
    local_login_sender_maps =
        inline:{ { root = *}, { postfix = * } },
        pcre:/etc/postfix/login_senders

/etc/postfix/login_senders:
   # Allow both the bare username and the user@domain forms.
    /(.+)/ $1 $1@example.com

Major changes - order of relay and recipient restrictions
---------------------------------------------------------

[Incompat 20210131] With smtpd_relay_before_recipient_restrictions=yes,
the Postfix SMTP server will evaluate smtpd_relay_restrictions before
smtpd_recipient_restrictions. This is the default behavior with
compatibility_level >= 3.6.

This change makes the implemented behavior consistent with existing
documentation. There is a backwards-compatibility warning that allows
users to freeze historical behavior. See COMPATIBILITY_README for
details.

Major changes - respectful logging
----------------------------------

[Feature 20210220] Postfix version 3.6 deprecates terminology
that implies white is better than black. Instead, Postfix prefers
'allowlist', 'denylist', and variations on those words. This change
affects Postfix documentation, and postscreen parameters and logging.

To keep the old postscreen logging set "respectful_logging = no"
in main.cf.

Noel Jones assisted with the initial transition.

Changes in documentation
------------------------

Postfix documentation was updated to use 'allowlist', 'denylist', etc.
These documentation changes do not affect Postfix behavior.

Changes in parameter names
--------------------------

The following postscreen parameters replace names that contain 'blacklist'
or 'whitelist':

    postscreen_allowlist_interfaces
    postscreen_denylist_action
    postscreen_dnsbl_allowlist_threshold

These new parameters have backwards-compatible default settings
that support the old parameter names, so that the name change should
not affect Postfix behavior. This means that existing management tools
that use the old parameter names should keep working as before.

This compatibility safety net may break when some management tools
use the new parameter names, and some use the old names, such that
different tools will disagree on how Postfix works.

Changes in logging
------------------

The following logging replaces forms that contain 'blacklist' or
'whitelist':

    postfix/postscreen[pid]: ALLOWLIST VETO [address]:port
    postfix/postscreen[pid]: ALLOWLISTED [address]:port
    postfix/postscreen[pid]: DENYLISTED [address]:port

To avoid breaking logfile analysis tools, Postfix keeps logging the old
forms by default, as long as the compatibility_level parameter setting
is less than 3.6, and the respectful_logging parameter is not explicitly
configured. As a reminder, Postfix will log the following:

    postfix/postscreen[pid]: Using backwards-compatible default setting
        respectful_logging=no for client [address]:port

To keep logging the old form, make the setting "respectful_logging =
no" permanent in main.cf, for example:

    # postconf "respectful_logging = no"
    # postfix reload

To stop the reminder, configure the respectful_logging parameter to
"yes" or "no", or configure "compatibility_level = 3.6".

Major changes - threaded bounces
--------------------------------

[Feature 20201205] Support for threaded bounces. This allows mail
readers to present a non-delivery, delayed delivery, or successful
delivery notification in the same email thread as the original
message.

Unfortunately, this also makes it easy for users to mistakenly delete
the whole email thread (all related messages), instead of deleting
only the delivery status notification.

To enable, specify "enable_threaded_bounces = yes".

Other changes - smtpd_sasl_mechanism_list
-----------------------------------------

[Feature 20200906] The smtpd_sasl_mechanism_list parameter (default:
!external, static:rest) prevents confusing errors when a SASL backend
announces EXTERNAL support which Postfix does not support.

Other changes - delivery logging
--------------------------------

[Incompat 20200531] Postfix delivery agents now log an explicit record
when delegating delivery to a different Postfix delivery agent.

For example, with "best_mx_transport = local", an SMTP delivery
agent will now log when a recipient will be delivered locally. This
makes the delegating delivery agent visible, where it would otherwise
have remained invisible, which would complicate troubleshooting.

  postfix/smtp[pid]: queueid: passing <recipient> to transport=local

This will usually be followed by logging for an actual delivery:

  postfix/local[pid]: queueid: to=<recipient>, relay=local, ...

Other examples: the local delivery agent will log a record that it
defers mailbox delivery through mailbox_transport or through
fallback_transport.

Other changes - error logging
-----------------------------

[Incompat 20200531] Postfix programs will now log "Application error"
instead of "Success" or "Unknown error: 0" when an operation fails with
errno == 0, i.e., the error originates from non-kernel code.

Other changes - dns lookups
---------------------------

[Feature 20200509] The threadsafe resolver API (res_nxxx() calls)
is now the default, not because the API is threadsafe, but because
this is the API where new features are being added.

To build old style, build with:

    make makefiles CCARGS="-DNO_RES_NCALLS..."

This is the default for systems that are known not to support the
threadsafe resolver API.