path: root/RELEASE_NOTES

This is the Postfix 3.4 (stable) release.

The stable Postfix release is called postfix-3.4.x where 3=major
release number, 4=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.5-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.2 or earlier, read RELEASE_NOTES-3.3
before proceeding.

Runtime detection of DNSSEC support
-----------------------------------

The Postfix build system will no longer automatically disable DNSSEC
support when it determines that Postfix will use libc-musl. This removes
the earlier libc-musl workaround for Postfix 3.2.15, 3.3.10, 3.4.12,
and 3.5.2.

Now, when a Postfix process requests DNSSEC support (typically, for
Postfix DANE support), the process may do a runtime test to determine if
DNSSEC validation is available. DNSSEC support may be broken because of
local configuration, libc incompatibility, or other infrastructure issues.

Background: DNSSEC validation is needed for Postfix DANE support;
this ensures that Postfix receives TLSA records with secure TLS
server certificate info. When DNSSEC validation is unavailable,
mail deliveries using opportunistic DANE will not be protected by
server certificate info in TLSA records, and mail deliveries using
mandatory DANE will not be made at all.

The dnssec_probe parameter specifies the DNS query type (default:
"ns") and DNS query name (default: ".") that Postfix may use to
determine whether DNSSEC validation is available. Specify an empty
value to disable this feature.

By default, a Postfix process will send a DNSSEC probe after 1) the
process made a DNS query that requested DNSSEC validation, 2) the
process did not receive a DNSSEC validated response to this query
or to an earlier query, and 3) the process did not already send a
DNSSEC probe.

When the DNSSEC probe has no response, or when the response is not
DNSSEC validated, Postfix logs a warning that DNSSEC validation may
be unavailable. Examples:

warning: DNSSEC validation may be unavailable
warning: reason: dnssec_probe 'ns:.' received a response that is not DNSSEC validated
warning: reason: dnssec_probe 'ns:.' received no response: Server failure

This feature was backported from Postfix 3.6.

libc-musl workaround for Postfix 3.2.15, 3.3.10, 3.4.12, and 3.5.2
------------------------------------------------------------------

Security: this release disables DANE support on Linux systems with
libc-musl, because libc-musl provides no indication whether DNS
responses are authentic. This broke DANE support without a clear
explanation.

TLS Workaround for Postfix 3.4.6, 3.3.5, 3.2.10 and 3.1.13
-----------------------------------------------------------

This release introduces a workaround for implementations that hang
Postfix while shutting down a TLS session, until Postfix times out.
With "tls_fast_shutdown_enable = yes" (the default), Postfix no
longer waits for a remote TLS peer to respond to a TLS 'close'
request. This behavior is recommended with TLSv1.0 and later. Specify
"tls_fast_shutdown_enable = no" to get historical Postfix behavior.

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.

Summary of changes
------------------

Incompatible changes, bdat support, containers, database support,
logging, safety, tls connection pooling, tls support, usability,

Incompatible changes
--------------------

[Incompat 20180826] The Postfix SMTP server announces CHUNKING (BDAT
command) by default. In the unlikely case that this breaks some
important remote SMTP client, disable the feature as follows:

/etc/postfix/main.cf:
    # The logging alternative:
    smtpd_discard_ehlo_keywords = chunking
    # The non-logging alternative:
    smtpd_discard_ehlo_keywords = chunking, silent_discard

See BDAT_README for more.

[Incompat 20190126] This introduces a new master.cf service 'postlog'
with type 'unix-dgram' that is used by the new postlogd(8) daemon.
Before backing out to an older Postfix version, edit the master.cf
file and remove the postlog entry.

[Incompat 20190106] Postfix 3.4 drops support for OpenSSL 1.0.1
(end-of-life was December 31, 2016) and all earlier releases.

[Incompat 20180701] To avoid performance loss under load, the
tlsproxy(8) daemon now requires a zero process limit in master.cf
(this setting is provided with the default master.cf file). By
default, a tlsproxy(8) process will retire after several hours.

To set the tlsproxy process limit to zero:

# postconf -F tlsproxy/unix/process_limit=0
# postfix reload

Major changes - bdat support
--------------------

[Feature 20180826] Postfix SMTP server support for RFC 3030 CHUNKING
(the BDAT command) without BINARYMIME, in both smtpd(8) and
postscreen(8). This has no effect on Milters, smtpd_mumble_restrictions,
and smtpd_proxy_filter. See BDAT_README for more.

Major changes - containers
--------------------------

[Feature 20190126] Support for logging to file or stdout, instead
of using syslog.

- Logging to file solves a usability problem for MacOS, and
  eliminates multiple problems with systemd-based systems.

- Logging to stdout is useful when Postfix runs in a container, as
  it eliminates a syslogd dependency.

See MAILLOG_README for configuration examples and logfile rotation.

[Feature 20180422] Better handling of undocumented(!) Linux behavior
whether or not signals are delivered to a PID=1 process.

Major changes - database support
--------------------------------

[Feature 20181105] Support for (key, list of filenames) in map
source text.

- Currently, this feature is used only by tls_server_sni_maps.

- When a map is created from source with "postmap -F maptype:mapname",
  the command processes each key as usual and processes each value
  as a list of filenames, concatenates the content of those files
  (with one newline character in-between files), and stores an entry
  with (key, base64-encoded result).

- When a map is queried with "postmap -F -q ...", the command
  base64-decodes each value. It reports an error when a value is
  not in base64 form.

  This "postmap -F -q ..." behavior also works when querying the
  memory-resident map types cidr:, inline:, pcre:, randmap:, regexp:,
  and static:. Postfix reads the files specified as table values,
  stores base64-encoded content, and base64-decodes content upon
  table lookup.

  Internally, Postfix will turn on this behavior for lookups (not
  updates) when a map is opened with the DICT_FLAG_RHS_IS_FILE flag.

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

[Feature 20190126] Support for logging to file or stdout, instead
of using syslog.

- Logging to file solves a usability problem for MacOS, and
  eliminates multiple problems with systemd-based systems.

- Logging to stdout is useful when Postfix runs in a container, as
  it eliminates a syslogd dependency.

See MAILLOG_README for configuration examples and logfile rotation.

Major changes - safety
----------------------

[Feature 20180623] Automatic retirement: dnsblog(8) and tlsproxy(8) process
will now voluntarily retire after after max_idle*max_use, or some
sane limit if either limit is disabled. Without this, a process
could stay busy for days or more.

Major changes - tls connection pooling
--------------------------------------

[Feature 20180617] Postfix SMTP client support for multiple deliveries
per TLS-encrypted connection. This is primarily to improve mail
delivery performance for destinations that throttle clients when
they don't combine deliveries.

This feature is enabled with "smtp_tls_connection_reuse=yes" in
main.cf, or with "tls_connection_reuse=yes" in smtp_tls_policy_maps.
It supports all Postfix TLS security levels including dane and
dane-only.

The implementation of TLS connection reuse relies on the same
scache(8) service as used for delivering plaintext SMTP mail, the
same tlsproxy(8) daemon as used by the postscreen(8) service for
inbound connections, and relies on the same hints from the qmgr(8)
daemon. It reuses the configuration parameters described in
CONNECTION_CACHE_README.

The Postfix SMTP client now logs whether an SMTP-over-TLS connection
is newly established ("TLS connection established") or whether the
connection is reused ("TLS connection reused").

The following illustrates how TLS connections are reused:

    Initial plaintext SMTP handshake:
      smtp(8) -> remote SMTP server

    Reused SMTP/TLS connection, or new SMTP/TLS connection:
      smtp(8) -> tlsproxy(8) -> remote SMTP server

    Cached SMTP/TLS connection:
      scache(8) -> tlsproxy(8) -> remote SMTP server

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

[Feature 20190106] SNI support in the Postfix SMTP server, the
Postfix SMTP client, and in the tlsproxy(8) daemon (both server and
client roles). See the postconf(5) documentation for the new
tls_server_sni_maps and smtp_tls_servername parameters.

[Feature 20190106] Support for files that contain multiple (key,
certificate, trust chain) instances. This was required to implement
server-side SNI table lookups, but it also eliminates the need for
separate cert/key files for RSA, DSA, Elliptic Curve, and so on.
The file format is documented in the TLS_README sections "Server-side
certificate and private key configuration" and "Client-side certificate
and private key configuration", and in the postconf(5) documentation
for the parameters smtp_tls_chain_files, smtpd_tls_chain_files,
tlsproxy_client_chain_files, and tlsproxy_tls_chain_files.

Note: the command "postfix tls" does not yet support the new
consolidated certificate chain format.  If you switch to the new
format, you'll need to manage your keys and certificates directly,
rather than via postfix-tls(1).

Major changes - usability
-------------------------

[Feature 20180812] Support for smtpd_reject_footer_maps (as well
as the postscreen variant postscreen_reject_footer_maps) for more
informative reject messages. This is indexed with the Postfix SMTP
server response text, and overrides the footer specified with
smtpd_reject_footer.  One will want to use a pcre: or regexp: map
with this.