diff options
Diffstat (limited to 'html/DEPRECATION_README.html')
| -rw-r--r-- | html/DEPRECATION_README.html | 411 |
1 files changed, 411 insertions, 0 deletions
diff --git a/html/DEPRECATION_README.html b/html/DEPRECATION_README.html new file mode 100644 index 0000000..4729568 --- /dev/null +++ b/html/DEPRECATION_README.html @@ -0,0 +1,411 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<html> + +<head> + +<title>Postfix Replacements for Deprecated Features </title> + +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link rel='stylesheet' type='text/css' href='postfix-doc.css'> + +</head> + +<body> + +<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix +Replacements for Deprecated Features</h1> + +<hr> + +<h2>Purpose of this document </h2> + +<p> This document describes Postfix features that are deprecated +(will be removed) or that have already been removed. It also has +tips for making an existing Postfix configuration more future-proof. +</p> + +<p> Overview: </p> + +<ul> + +<li> <a href="#why"> Why deprecate? </a> + +<li> <a href="#process"> Deprecation process </a> + +<li> <a href="#features"> Deprecated features </a> + +</ul> + +<h2> <a name="why"> Why deprecate? </a> </h2> + +<p> Sometimes, a Postfix feature needs to be replaced with a different +one. To give an example: </p> + +<ul> + +<li> <p> The initial Postfix TLS implementation used multiple boolean +parameters: one parameter to enable opportunistic TLS (for example, +"<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes") and one parameter to enable mandatory TLS +(for example, "smtp_require_tls = yes"). </p> + +<li> <p> As we added support more features such as fingerprint, +dane, and so on, we decided not to add more boolean parameters. +Instead we introduced one configuration parameter to select from +multiple deployment models (for example, <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = +may | encrypt | dane, etc...). </p> + +</ul> + +<!-- + +<p> Over time it has become clear that 'level' is too rigid, so this may +have to change again. Wietse and Viktor have been discussing a way to +specify a range with minimum properties that are required (e.g., encrypt) +and nice-to-have properties if they are available (dane or mta-sts). </p> + +--> + +<p> Having both the "old" and "new" way to configure Postfix is +convenient for existing Postfix installations, because their +configuration does not break after an upgrade to a new version. +Unfortunately, there are also disadvantages. Having multiple ways +to do similar things is not only confusing for newcomers, it also +makes Postfix harder to change. </p> + +<h2> <a name="process"> Deprecation process </a> </h2> + +<p> The basic process steps are: </p> + +<ol> + +<li> <p> Inform humans that a feature will be removed, and suggest +replacements, in logging and documentation. </p> + +<li> <p> Remove the feature, and update logging and documentation. </p> + +</ol> + +<p> Disclaimer: it has taken 20 years for some features to be +removed. This past is not a guarantee for the future. </p> + +<h2> <a name="features"> Deprecated features </a> </h2> + +<p> The table summarizes removed or deprecated features and +replacements. Click on the "obsolete feature" name for a more +detailed description. </p> + +<blockquote> + +<table border="1"> + +<tr> <th> Obsolete feature name </th> <th> Warning as <br> of version +</th> <th> Removed <br> in version </th> <th> Replacement </th> +</tr> + +<tr> <td> <a href="#disable_dns_lookups"> disable_dns_lookups </a> +</td> <td align="center"> 3.9 </td> <td align="center"> - </td> +<td> <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> </td> </tr> + +<tr> <td> <a href="#xxx_enforce_tls"> <i>xxx</i>_use_tls </a> </td> +<td align="center"> 3.9 </td> <td align="center"> - </td> <td> +<i>xxx</i>_tls_security_level </td> </tr> + +<tr> <td> <a href="#xxx_enforce_tls"> <i>xxx</i>_enforce_tls </a> +</td> <td align="center"> 3.9 </td> <td align="center"> - </td> +<td> <i>xxx</i>_tls_security_level </td> </tr> + +<tr> <td> <a href="#xxx_per_site"> <i>xxx</i>_per_site </a> </td> +<td align="center"> 3.9 </td> <td align="center"> - </td> <td> +<i>xxx</i>_policy_maps </td> </tr> + +<tr> <td> <a href="#smtpd_tls_dh1024_param_file"> +smtpd_tls_dh1024_param_file </a> </td> <td align="center"> 3.9 </td> +<td align="center"> - </td> <td> do not specify (leave at default) +</td> </tr> + +<tr> <td> <a href="#smtpd_tls_eecdh_grade"> smtpd_tls_eecdh_grade +</a> </td> <td align="center"> 3.9 </td> <td align="center"> - </td> +<td> do not specify (leave at default) </td> </tr> + +<tr> <td> <a href="#permit_mx_backup"> permit_mx_backup </a> </td> +<td align="center"> 3.9 </td> <td align="center"> - </td> <td> +<a href="postconf.5.html#relay_domains">relay_domains</a> </td> </tr> + +<tr> <td> <a href="#check_relay_domains"> check_relay_domains </a> +</td> <td align="center"> 2.2 </td> <td align="center"> 3.9 </td> +<td> <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> </td> </tr> + +<tr> <td> <a href="#reject_maps_rbl"> reject_maps_rbl </a> </td> +<td align="center"> 2.1 </td> <td align="center"> 3.9 </td> <td> +<a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> </td> </tr> + +<tr> <td> <a href="#permit_naked_ip_address"> permit_naked_ip_address +</a> </td> <td align="center"> 2.0 </td> <td align="center"> 3.9 +</td> <td> <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a> </td> </tr> + +</table> + +</blockquote> + +<h3> <a name="disable_dns_lookups"> Obsolete DNS on/off configuration +</a> </h3> + +<p> The <a href="postconf.1.html">postconf(1)</a> command logs the following: </p> + +<ul> + +<li> support for parameter "<a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a>" will be removed; instead, specify "<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>" + +</ul> + +<p> Replace obsolete configuration with its replacement: </p> + +<blockquote> + +<table border="1"> + +<tr> <th width="33%"> Goal </th> <th width="33%"> Obsolete configuration +</th> <th> Replacement configuration </th> </tr> + +<tr> <td> To disable DNS lookups in the Postfix SMTP/LMTP client +</td> <td> <a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> = yes </td> <td> <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> += disabled </td> </tr> + +<tr> <td> To enable DNS lookups in the Postfix SMTP/LMTP client </td> <td> +<a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> = no </td> <td> +Leave <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> at the implicit default which is empty, unless +you need a higher support level such as DNSSEC. </td> </tr> + +</table> + +</blockquote> + +<h3> <a name="xxx_use_tls"> Obsolete opportunistic TLS configuration +</a> </h3> + +<p> The <a href="postconf.1.html">postconf(1)</a> command logs one of the following: </p> + +<ul> + +<li> support for parameter "<a href="postconf.5.html#lmtp_use_tls">lmtp_use_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#lmtp_tls_security_level">lmtp_tls_security_level</a>" + +<li> support for parameter "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>" + +<li> support for parameter "<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>" + +</ul> + +<p> There are similarly-named parameters and warnings for <a href="postscreen.8.html">postscreen(8)</a> +and <a href="tlsproxy.8.html">tlsproxy(8)</a>, but those parameters should rarely be specified +by hand. </p> + +<p> Replace obsolete configuration with its replacement: </p> + +<blockquote> + +<table border="1"> + +<tr> <th width="33%"> Goal </th> <th width="33%"> Obsolete configuration </th> <th> Replacement configuration </th> </tr> + +<tr> <td> To turn off TLS </td> <td> <i>xxx</i>_use_tls = no </td> +<td> <i>xxx</i>_security_level = none </td> </tr> + +<tr> <td> To turn on opportunistic TLS </td> <td> <i>xxx</i>_use_tls += yes </td> <td> <i>xxx</i>_security_level = may </td> </tr> + +</table> + +</blockquote> + +<h3> <a name="xxx_enforce_tls"> Obsolete mandatory TLS configuration +</a> </h3> + +<p> The <a href="postconf.1.html">postconf(1)</a> command logs one of the following: </p> + +<ul> + +<li> support for parameter "<a href="postconf.5.html#lmtp_enforce_tls">lmtp_enforce_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#lmtp_tls_security_level">lmtp_tls_security_level</a>" + +<li> support for parameter "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>" + +<li> support for parameter "<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>" will be removed; instead, specify "<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>" + +</ul> + +<p> There are similarly-named parameters and warnings for <a href="postscreen.8.html">postscreen(8)</a> +and <a href="tlsproxy.8.html">tlsproxy(8)</a>, but those parameters should rarely be specified +by hand. </p> + +<p> Replace obsolete configuration with its replacement: </p> + +<blockquote> + +<table border="1"> + +<tr> <th width="33%"> Goal </th> <th width="33%"> Obsolete configuration </th> <th> Replacement configuration </th> </tr> + +<tr> <td> To turn off mandatory TLS </td> <td> <i>xxx</i>_enforce_tls += no </td> <td> <i>xxx</i>_security_level = may </td> </tr> + +<tr> <td> To turn on mandatory TLS </td> <td> <i>xxx</i>_enforce_tls += yes </td> <td> <i>xxx</i>_security_level = encrypt </td> </tr> + +</table> + +</blockquote> + +<h3> <a name="xxx_per_site"> Obsolete TLS policy table configuration +</a> </h3> + +<p> The <a href="postconf.1.html">postconf(1)</a> command logs one of the following: </p> + +<ul> + +<li> support for parameter "<a href="postconf.5.html#lmtp_tls_per_site">lmtp_tls_per_site</a>" will be removed; +instead, specify "<a href="postconf.5.html#lmtp_tls_policy_maps">lmtp_tls_policy_maps</a>" + +<li> support for parameter "<a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a>" will be removed; +instead, specify "<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>" + +</ul> + +<p> There is similarly-named parameter and warning for <a href="tlsproxy.8.html">tlsproxy(8)</a>, +but that parameter should rarely be specified by hand. </p> + +<p> Unfortunately, this is more than a name change: the table format +has changed too, as has the table search process. There is no simple +conversion of the obsolete form to its replacement. </p> + +<h3> <a name="check_relay_domains"> check_relay_domains </a> </h3> + +<p> Depending on the Postfix version, the Postfix SMTP daemon logs +following warning: </p> + +<ul> + +<li> support for restriction "check_relay_domains" has been removed +in Postfix 3.9"; instead, specify "<a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>" + +<li> support for restriction "check_relay_domains" will be removed +from Postfix; use "<a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>" instead + +</ul> + +<p> This feature was removed because it would relay based on the +client domain name, which is not robust. </p> + +<p> Recommended configuration to prevent an "open relay" problem +with the SMTP service on port 25: +</p> + +<blockquote> +<pre> +<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = + <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, + <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>, + <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> + ...other restrictions... +</pre> +</blockquote> + +<p> Or equivalent in <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>. </p> + +<h3> <a name="permit_mx_backup"> permit_mx_backup</a> </h3> + +<p> The Postfix version 3.9 and later SMTP daemon logs the following +warning: </p> + +<ul> + +<li> support for restriction "<a href="postconf.5.html#permit_mx_backup">permit_mx_backup</a>" will be removed +from Postfix; instead, specify "<a href="postconf.5.html#relay_domains">relay_domains</a>" + +</ul> + +<p> This feature will be removed because it is too difficult to +configure recipient address validation, making Postfix a source of +backscatter bounces. </p> + +<p> To specify the domains that Postfix will provide MX backup +service for, see <a href="STANDARD_CONFIGURATION_README.html#backup"> +Configuring Postfix as primary or backup MX host for a remote +site</a>. </p> + +<h3> <a name="reject_maps_rbl"> reject_maps_rbl</a> </h3> + +<p> Depending on the Postfix version, the SMTP daemon logs one of +the following warnings: </p> + +<ul> + +<li> support for restriction "reject_maps_rbl" has been removed in +Postfix 3.9"; instead, specify "<a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> domain-name" + +<li> support for restriction "reject_maps_rbl" will be removed from +Postfix; use "<a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> domain-name" instead + +</ul> + +<p> This feature was replaced because "MAPS RBL" is the name of a +specific reputation service. The <a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> feature provides +a superset of the reject_maps_rbl functionality. </p> + +<p> Recommended configuration: </p> + +<blockquote> +<pre> +<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = + <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, + <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>, + <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> + <a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> <i>domain-name</i> + ...other restrictions... +</pre> +</blockquote> + +<p> Where <i>domain-name</i> is the domain name of a DNS reputation service. </p> + +<h3> <a name="permit_naked_ip_address"> permit_naked_ip_address</a> </h3> + +<p> Depending on the Postfix version, the SMTP daemon logs one of +the following warnings: </p> + +<ul> + +<li> support for restriction "permit_naked_ip_address" has been +removed in Postfix 3.9"; instead, specify "<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>" or +"<a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>" + +<li> restriction permit_naked_ip_address is deprecated. Use +<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> or <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a> instead + +</ul> + +<p> This feature was removed because it was easy to get a false +match when <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> was intended to match a +remote SMTP client IP address. </p> + +<p> Recommended configuration: </p> + +<blockquote> +<pre> +<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = + <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, + <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>, + <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> + <a href="postconf.5.html#reject_rbl_client">reject_rbl_client</a> <i>domain-name</i> + ...other restrictions... +</pre> +</blockquote> + +<p> That is, no restriction on HELO or EHLO syntax. Such restrictions +ar rarely useful nowadays. + +</body> + +</html> |