RELEASE_NOTES-2.5

The stable Postfix release is called postfix-2.5.x where 2=major
release number, 5=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-2.6-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.

Incompatibility with Postfix 2.3 and earlier
--------------------------------------------

If you upgrade from Postfix 2.3 or earlier, read RELEASE_NOTES-2.4
before proceeding.

Major changes - critical
------------------------

[Incompat 20071224] The protocol to send Milter information from
smtpd(8) to cleanup(8) processes was cleaned up. If you use the
Milter feature, and upgrade a live Postfix system, you may see an
"unexpected record type" warning from a cleanup(8) server process.
To prevent this, execute the command "postfix reload".  The
incompatibility affects only systems that use the Milter feature.
It does not cause loss of mail, just a minor delay until the remote
SMTP client retries.

[Incompat 20071212] The allow_min_user feature now applies to both
sender and recipient addresses in SMTP commands. With earlier Postfix
versions, only recipients were subject to the allow_min_user feature,
and the restriction took effect at mail delivery time, causing mail
to be bounced later instead of being rejected immediately.

[Incompat 20071206] The "make install" and "make upgrade" procedures
now create a Postfix-owned directory for Postfix-writable data files
such as caches and random numbers. The location is specified with
the "data_directory" parameter (default: "/var/lib/postfix"), and
the ownership is specified with the "mail_owner" parameter.

[Incompat 20071206] The tlsmgr(8) and verify(8) servers no longer
use root privileges when opening the address_verify_map,
*_tls_session_cache_database, and tls_random_exchange_name cache
files.  This avoids a potential security loophole where the ownership
of a file (or directory) does not match the trust level of the
content of that file (or directory).

[Incompat 20071206] The tlsmgr(8) and verify(8) cache files should
now be stored as Postfix-owned files under the Postfix-owned
data_directory.  As a migration aid, attempts to open these files
under a non-Postfix directory are redirected to the Postfix-owned
data_directory, and a warning is logged.

This is an example of the warning messages:

    Dec  6 12:56:22 bristle postfix/tlsmgr[7899]: warning: request
	to update file /etc/postfix/prng_exch in non-postfix directory
	/etc/postfix

    Dec  6 12:56:22 bristle postfix/tlsmgr[7899]: warning: redirecting
	the request to postfix-owned data_directory /var/lib/postfix

If you wish to continue using a pre-existing tls_random_exchange_name
or address_verify_map file, move it to the Postfix-owned data_directory
and change ownership from root to Postfix (that is, change ownership
to the account specified with the mail_owner configuration parameter).

[Feature 20071205] The "make install" and "make upgrade" procedures
now create a Postfix-owned directory for Postfix-writable data files
such as caches and random numbers. The location is specified with
the "data_directory" parameter (default: "/var/lib/postfix"), and
the ownership is specified with the "mail_owner" parameter.

[Incompat 20071203] The "make upgrade" procedure adds a new service
"proxywrite" to the master.cf file, for read/write lookup table
access. If you copy your old configuration file over the updated
one, you may see warnings in the maillog file like this:

   connect #xx to subsystem private/proxywrite: No such file or directory

To recover, run "postfix upgrade-configuration" again.

[Incompat 20070613] The pipe(8) delivery agent no longer allows
delivery with the same group ID as the main.cf postdrop group.

Major changes - malware defense
-------------------------------

[Feature 20080107] New "pass" service type in master.cf.  Written
years ago, this allows future front-end daemons to accept all
connections from the network, and to hand over connections from
well-behaved clients to Postfix.  Since this feature uses file
descriptor passing, it imposes no overhead once a connection is
handed over to Postfix.  See master(5) for a few details.

[Feature 20070911] Stress-adaptive behavior. When a "public" network
service runs into an "all processes are busy" condition, the master(8)
daemon logs a warning, restarts the service, and runs it with "-o
stress=yes" on the command line (under normal conditions it runs
the service with "-o stress=" on the command line).  This can be
used to make main.cf parameter settings stress dependent, for
example:

/etc/postfix/main.cf:
    smtpd_timeout = ${stress?10}${stress:300}
    smtpd_hard_error_limit = ${stress?1}${stress:20}

Translation: under conditions of stress, use an smtpd_timeout value
of 10 seconds instead of 300, and use smtpd_hard_error_limit of 1
instead of 20. The syntax is explained in the postconf(5) manpage.

The STRESS_README file gives examples of how to mitigate flooding
problems.

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

[Incompat 20080109] TLS logging output has changed to make it more
useful. Existing logfile parser regular expressions may need
adjustment.

- More log entries include the "hostnamename[ipaddress]" of the
  remote SMTP peer.

- Certificate trust chain error reports show only the first
  error certificate (closest to the trust chain root), and the
  reporting is more human-readable for the most likely errors.

- After the completion of the TLS handshake, the session is logged
  with TLS loglevel >= 1 as either "Untrusted", "Trusted" or
  "Verified" (SMTP client only).
  - "Untrusted" means that the certificate trust chain is invalid,
    or that the root CA is not trusted.
  - "Trusted" means that the certificate trust chain is valid, and
    that the root CA is trusted.
  - "Verified" means that the certificate meets the SMTP client's
    matching criteria for the destination:
    - In the case of a destination name match, "Verified" also
      implies "Trusted".
    - In the case of a fingerprint match, CA trust is not applicable.

- The logging of protocol states with TLS loglevel >= 2 no longer
  reports bogus error conditions when OpenSSL asks Postfix to refill
  (or flush) network I/O buffers.  This loglevel is for debugging
  only; use 0 or 1 in production configurations.

[Feature 20080109] The Postfix SMTP client has a new "fingerprint"
security level.  This avoids dependencies on CAs, and relies entirely
on bi-lateral exchange of public keys (really self-signed or private
CA signed X.509 public key certificates). Scalability is clearly
limited. For details, see the fingerprint discussion in TLS_README.

[Feature 20080109] The Postfix SMTP server can now use SHA1 instead
of MD5 to compute remote SMTP client certificate fingerprints. For
backwards compatibility, the default algorithm is MD5.  For details,
see the "smtpd_tls_fingerprint_digest" parameter in the postconf(5)
manual.

[Feature 20080109] The maximum certificate trust chain depth
(verifydepth) is finally implemented in the Postfix TLS library.
Previously, the parameter had no effect. The default depth was
changed to 9 (the OpenSSL default) for backwards compatibility.

If you have explicity limited the verification depth in main.cf,
check that the configured limit meets your needs. See the
"lmtp_tls_scert_verifydepth", "smtp_tls_scert_verifydepth" and
"smtpd_tls_ccert_verifydepth" parameters in the postconf(5) manual.

[Feature 20080109] The selection of SSL/TLS protocols for mandatory
TLS can now use exclusion rather than inclusion. Either form is
acceptable; see the "lmtp_tls_mandatory_protocols",
"smtp_tls_mandatory_protocols" and "smtpd_tls_mandatory_protocols"
parameters in the postconf(5) manual.

Major changes - scheduler
-------------------------

[Feature 20071130] Revised queue manager with separate mechanisms
for per-destination concurrency control and for dead destination
detection.  The concurrency control supports less-than-1 feedback
to allow for more gradual concurrency adjustments, and uses hysteresis
to avoid rapid oscillations.  A destination is declared "dead" after
a configurable number of pseudo-cohorts(*) reports connection or
handshake failure.

(*) A pseudo-cohort is a number of delivery requests equal to a
    destination's delivery concurrency.

The drawbacks of the old +/-1 feedback scheduler are a) overshoot
due to exponential delivery concurrency growth with each pseudo-cohort(*)
(5-10-20...); b) throttling down to zero concurrency after a single
pseudo-cohort(*) failure. The latter was especially an issue with
low-concurrency channels where a single failure could be sufficient
to mark a destination as "dead", and suspend further deliveries.

New configuration parameters: destination_concurrency_feedback_debug,
default_destination_concurrency_positive_feedback,
default_destination_concurrency_negative_feedback,
default_destination_concurrency_failed_cohort_limit, as well as
transport-specific versions of the same.

The default parameter settings are backwards compatible with older
Postfix versions. This may change after better defaults are field
tested.

The updated SCHEDULER_README document describes the theory behind
the new concurrency scheduler, as well as Patrik Rak's preemptive
job scheduler. See postconf(5) for more extensive descriptions of
the configuration parameters.

Major changes - small/home office
---------------------------------

[Feature 20080115] Preliminary SOHO_README document that combines
bits and pieces from other document in one place, so that it is
easier to find. This document describes the "mail sending" side
only.

[Feature 20071202] Output rate control in the queue manager. For
example, specify "smtp_destination_rate_delay = 5m", to pause five
minutes between message deliveries. More information in the postconf(5)
manual under "default_destination_rate_delay".

Major changes - smtp client
---------------------------

[Incompat 20080114] The Postfix SMTP client now by default defers
mail after a remote SMTP server rejects a SASL authentication
attempt.  Specify "smtp_sasl_auth_soft_bounce = no" for the old
behavior.

[Feature 20080114] The Postfix SMTP client can now avoid making
repeated SASL login failures with the same server, username and
password.  To enable this safety feature, specify for example
"smtp_sasl_auth_cache_name = proxy:btree:/var/lib/postfix/sasl_auth_cache"
(access through the proxy service is required). Instead of trying
to SASL authenticate, the Postfix SMTP client defers or bounces
mail as controlled with the new smtp_sasl_auth_soft_bounce configuration
parameter.

[Feature 20071111] Header/body checks are now available in the SMTP
client, after the implementation was moved from the cleanup server
to a library module.  The SMTP client provides only actions that
don't change the message delivery time or destination: warn, replace,
prepend, ignore, dunno, ok.

[Incompat 20070614] By default, the Postfix Cyrus SASL client no
longer sends a SASL authoriZation ID (authzid); it sends only the
SASL authentiCation ID (authcid) plus the authcid's password. Specify
"send_cyrus_sasl_authzid = yes" to get the old behavior.

Major changes - smtp server
---------------------------

[Feature 20070724] Not really major. New support for RFC 3848
(Received: headers with ESMTPS, ESMTPA, or ESMTPSA); updated SASL
support according to RFC 4954, resulting in small changes to SMTP
reply codes and (DSN) enhanced status codes.

Major changes - milter
----------------------

[Incompat 20071224] The protocol to send Milter information from
smtpd(8) to cleanup(8) processes was cleaned up. If you use the
Milter feature, and upgrade a live Postfix system, you may see an
"unexpected record type" warning from a cleanup(8) server process.
To prevent this, execute the command "postfix reload".  The
incompatibility affects only systems that use the Milter feature.
It does not cause loss of mail, just a minor delay until the remote
SMTP client retries.

[Feature 20071221] Support for most of the Sendmail 8.14 Milter
protocol features.

To enable the new features specify "milter_protocol = 6" and link
the filter application with a libmilter library from Sendmail 8.14
or later.

Sendmail 8.14 Milter features supported at this time:

- NR_CONN, NR_HELO, NR_MAIL, NR_RCPT, NR_DATA, NR_UNKN, NR_HDR, 
  NR_EOH, NR_BODY: The filter can tell Postfix that it won't reply
  to some of the SMTP events that Postfix sends. This makes the      
  protocol less chatty and improves performance.

- SKIP: The filter can tell Postfix to skip sending the rest of    
  the message body, which also improves performance.

- HDR_LEADSPC: The filter can request that Postfix does not delete 
  the first space character between header name and header value       
  when sending a header to the filter, and that Postfix does not
  insert a space character between header name and header value 
  when receiving a header from the filter.  This fixes a limitation
  in the old Milter protocol that can break DKIM and DK signatures.

- SETSYMLIST: The filter can override one or more of the main.cf
  milter_xxx_macros parameter settings.
 
Sendmail 8.14 Milter features not supported at this time:

- RCPT_REJ: report rejected recipients to the mail filter. 

- CHGFROM: replace sender, with optional ESMTP command parameters.

- ADDRCPT_PAR: add recipient, with optional ESMTP command parameters.

It is unclear when (if ever) the missing features will be implemented.
SMFIP_RCPT_REJ requires invasive changes in the SMTP server recipient
processing and error handling.  SMFIR_CHGFROM and SMFIR_ADDRCPT_PAR
require ESMTP command-line parsing in the cleanup server. Unfortunately,
Sendmail's documentation does not specify what ESMTP options are
supported, but only discusses examples of things that don't work.

Major changes - address verification
------------------------------------

[Incompat 20070514] The default sender address for address verification
probes was changed from "postmaster" to "double-bounce", so that
the Postfix SMTP server no longer causes surprising behavior by
excluding "postmaster" from SMTP server access controls.

Major changes - ldap
--------------------

[Incompat 20071216] Due to an incompatible API change between
OpenLDAP 2.0.11 and 2.0.12, an LDAP client compiled for OpenLDAP
version <= 2.0.11 will refuse to work with an OpenLDAP library
version >= 2.0.12 and vice versa.

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

[Incompat 20080109] TLS logging output has changed to make it more
useful. Existing logfile parser regular expressions may need
adjustment.

- More log entries include the "hostnamename[ipaddress]" of the
  remote SMTP peer.

- Certificate trust chain error reports show only the first
  error certificate (closest to the trust chain root), and the
  reporting is more human-readable for the most likely errors.

- After the completion of the TLS handshake, the session is logged
  with TLS loglevel >= 1 as either "Untrusted", "Trusted" or
  "Verified" (SMTP client only).
  - "Untrusted" means that the certificate trust chain is invalid,
    or that the root CA is not trusted.
  - "Trusted" means that the certificate trust chain is valid, and
    that the root CA is trusted.
  - "Verified" means that the certificate meets the SMTP client's
    matching criteria for the destination:
    - In the case of a destination name match, "Verified" also
      implies "Trusted".
    - In the case of a fingerprint match, CA trust is not applicable.

- The logging of protocol states with TLS loglevel >= 2 no longer
  reports bogus error conditions when OpenSSL asks Postfix to refill
  (or flush) network I/O buffers.  This loglevel is for debugging
  only; use 0 or 1 in production configurations.

[Incompat 20071216] The SMTP "transcript of session" email now
includes the remote SMTP server TCP port number.

Major changes - loop detection
------------------------------

[Incompat 20070422] [Incompat 20070422] When the pipe(8) delivery
agent is configured to create the optional Delivered-To: header,
it now first checks if that same header is already present in the
message. If so, the message is returned as undeliverable. This test
should have been included with Postfix 2.0 when Delivered-To: support
was added to the pipe(8) delivery agent.