1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix Backwards-Compatibility Safety Net</title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 11 12</head> 13 14<body> 15 16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 17Backwards-Compatibility Safety Net</h1> 18 19<hr> 20 21<h2>Purpose of this document </h2> 22 23<p> Postfix 3.0 introduces a safety net that runs Postfix programs 24with backwards-compatible default settings after an upgrade. The 25safety net will log a warning whenever a "new" default setting could 26have an negative effect on your mail flow. </p> 27 28<p>This document provides information on the following topics: </p> 29 30<ul> 31 32<li> <p> <a href="#overview">Detailed descriptions</a> of Postfix 33backwards-compatibility warnings. 34 35<li> <p> What backwards-compatible settings you may have to make 36permanent in <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a>. </p> 37 38<li> <p> <a href="#turnoff">How to turn off</a> Postfix 39backwards-compatibility warnings. </p> 40 41</ul> 42 43<h2> <a name="overview"> Overview </a> </h2> 44 45<p> With backwards compatibility turned on, Postfix logs a message 46whenever a backwards-compatible default setting may be required for 47continuity of service. Based on this logging the system administrator 48can decide if any backwards-compatible settings need to be made 49permanent in main.cf or master.cf, before <a href="#turnoff">turning 50off the backwards-compatibility safety net</a> as described at the 51end of this document. </p> 52 53<p> The following messages may be logged: </p> 54 55<ul> 56 57<li> <p> <a href="#append_dot_mydomain"> Using backwards-compatible 58default setting append_dot_mydomain=yes </a> </p> 59 60<li> <p> <a href="#chroot"> Using backwards-compatible default setting 61chroot=y</a> </p> 62 63<li><p> <a href="#relay_restrictions"> Using backwards-compatible 64default setting smtpd_relay_restrictions = (empty)</a> </p> 65 66<li> <p> <a href="#mynetworks_style"> Using backwards-compatible 67default setting mynetworks_style=subnet </a> </p> 68 69<li> <p> <a href="#relay_domains"> Using backwards-compatible default 70setting relay_domains=$mydestination </a> </p> 71 72<li> <p> <a href="#smtputf8_enable"> Using backwards-compatible 73default setting smtputf8_enable=no</a> </p> 74 75</ul> 76 77<p> If such a message is logged in the context of a legitimate 78request, the system administrator should make the backwards-compatible 79setting permanent in <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a>, as detailed in the 80sections that follow. </p> 81 82<p> When no more backwards-compatible settings need to be made 83permanent, the system administrator should <a href="#turnoff">turn 84off the backwards-compatibility safety net</a> as described at the 85end of this document. </p> 86 87<h2> <a name="append_dot_mydomain"> Using backwards-compatible default 88setting append_dot_mydomain=yes</a> </h2> 89 90<p> The <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> default value has changed from "yes" 91to "no". This could result in unexpected non-delivery of email after 92Postfix is updated from an older version. The backwards-compatibility 93safety net is designed to prevent such surprises. </p> 94 95<p> As long as the <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> parameter is left at 96its implicit default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is 97less than 1, Postfix may log one of the following messages:</p> 98 99<ul> 100 101<li> <p> Messages about missing "localhost" in <a href="postconf.5.html#mydestination">mydestination</a> or 102other address class: </p> 103 104<blockquote> 105<pre> 106postfix/trivial-rewrite[14777]: using backwards-compatible 107 default setting <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes to rewrite 108 "localhost" to "localhost.example.com"; please add 109 "localhost" to <a href="postconf.5.html#mydestination">mydestination</a> or other address class 110</pre> 111</blockquote> 112 113<p> If Postfix logs the above message, add "localhost" to 114<a href="postconf.5.html#mydestination">mydestination</a> (or <a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a>, <a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>, 115or <a href="postconf.5.html#relay_domains">relay_domains</a>) and execute the command "<b>postfix reload</b>". 116 117<li> <p> Messages about incomplete domains in email addresses: </p> 118 119<blockquote> 120<pre> 121postfix/trivial-rewrite[25835]: using backwards-compatible 122 default setting <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes to rewrite "foo" to 123 "foo.example.com" 124</pre> 125</blockquote> 126 127<p> If Postfix logs the above message for domains different from 128"localhost", and the sender cannot be changed to use complete domain 129names in email addresses, then the system administrator should make 130the backwards-compatible setting "<a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a> = yes" permanent 131in <a href="postconf.5.html">main.cf</a>: </p> 132 133<blockquote> 134<pre> 135# <b>postconf <a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b> 136# <b>postfix reload</b> 137</pre> 138</blockquote> 139 140</ul> 141 142<h2> <a name="chroot"> Using backwards-compatible default 143setting chroot=y</a> </h2> 144 145<p> The <a href="master.5.html">master.cf</a> chroot default value has changed from "y" (yes) 146to "n" (no). The new default avoids the need for copies of system 147files under the Postfix queue directory. However, sites with strict 148security requirements may want to keep the chroot feature enabled 149after updating Postfix from an older version. The backwards-compatibility 150safety net is designed allow the administrator to choose if they 151want to keep the old behavior. </p> 152 153<p> As long as a <a href="master.5.html">master.cf</a> chroot field is left at its 154implicit default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting 155is less than 1, Postfix may log the following message while it 156reads the <a href="master.5.html">master.cf</a> file: </p> 157 158<blockquote> 159<pre> 160postfix/master[27664]: /etc/postfix/<a href="master.5.html">master.cf</a>: line 72: using 161 backwards-compatible default setting chroot=y 162</pre> 163</blockquote> 164 165<p> If this service should remain chrooted, then the system 166administrator should make the backwards-compatible setting "chroot 167= y" permanent in <a href="master.5.html">master.cf</a>. For example, to update the chroot 168setting for the "smtp inet" service: </p> 169 170<blockquote> 171<pre> 172# <b>postconf -F smtp/inet/chroot=y</b> 173# <b>postfix reload</b> 174</pre> 175</blockquote> 176 177<h2> <a name="relay_restrictions"> Using backwards-compatible default 178setting smtpd_relay_restrictions = (empty)</a> </h2> 179 180<p> The <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> feature was introduced with Postfix 181version 2.10, as a safety mechanism for configuration errors in 182<a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> that could make Postfix an open relay. 183</p> 184 185<p> The <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> implicit default setting forbids 186mail to remote destinations from clients that don't match 187<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> or <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>. This could result 188in unexpected 'Relay access denied' errors after Postfix is updated 189from an older Postfix version. The backwards-compatibility safety 190net is designed to prevent such surprises. </p> 191 192<p> When the <a href="postconf.5.html#compatibility_level">compatibility_level</a> less than 1, and the 193<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> parameter is left at its implicit default 194setting, Postfix may log the following message: </p> 195 196<blockquote> 197<pre> 198postfix/smtpd[38463]: using backwards-compatible default setting 199 "<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> = (empty)" to avoid "Relay access 200 denied" error for recipient "user@example.com" from client 201 "host.example.net[10.0.0.2]" 202</pre> 203</blockquote> 204 205<p> If this request should not be blocked, then the system 206administrator should make the backwards-compatible setting 207"<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=" (i.e. empty) permanent in <a href="postconf.5.html">main.cf</a>: 208 209<blockquote> 210<pre> 211# <b>postconf <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=</b> 212# <b>postfix reload</b> 213</pre> 214</blockquote> 215 216<h2> <a name="mynetworks_style"> Using backwards-compatible default 217setting mynetworks_style=subnet</a> </h2> 218 219<p> The <a href="postconf.5.html#mynetworks_style">mynetworks_style</a> default value has changed from "subnet" 220to "host". This parameter is used to implement the "<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>" 221feature. The change could in unexpected 'access denied' errors after 222Postfix is updated from an older version. The backwards-compatibility 223safety net is designed to prevent such surprises. </p> 224 225<p> As long as the <a href="postconf.5.html#mynetworks">mynetworks</a> and <a href="postconf.5.html#mynetworks_style">mynetworks_style</a> parameters are 226left at their implicit default values, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> 227setting is less than 2, the Postfix SMTP server may log one of the 228following messages: </p> 229 230<blockquote> 231<pre> 232postfix/smtpd[17375]: using backwards-compatible default setting 233 <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet to permit request from client 234 "foo.example.com[10.1.1.1]" 235</pre> 236</blockquote> 237 238<blockquote> 239<pre> 240postfix/postscreen[24982]: using backwards-compatible default 241 setting <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet to permit request from client 242 "10.1.1.1" 243</pre> 244</blockquote> 245 246<p> If the client request should not be rejected, then the system 247administrator should make the backwards-compatible setting 248"<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = subnet" permanent in <a href="postconf.5.html">main.cf</a>: </p> 249 250<blockquote> 251<pre> 252# <b>postconf <a href="postconf.5.html#mynetworks_style">mynetworks_style</a>=subnet</b> 253# <b>postfix reload</b> 254</pre> 255</blockquote> 256 257<h2><a name="relay_domains"> Using backwards-compatible default 258setting relay_domains=$mydestination </a> </h2> 259 260<p> The <a href="postconf.5.html#relay_domains">relay_domains</a> default value has changed from "$<a href="postconf.5.html#mydestination">mydestination</a>" 261to the empty value. This could result in unexpected 'Relay access 262denied' errors or ETRN errors after Postfix is updated from an older 263version. The backwards-compatibility safety net is designed to 264prevent such surprises. </p> 265 266<p> As long as the <a href="postconf.5.html#relay_domains">relay_domains</a> parameter is left at its implicit 267default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is less than 2, 268Postfix may log one of the following messages. </p> 269 270<ul> 271 272<li> <p> Messages about accepting mail for a remote domain:</p> 273 274<blockquote> 275<pre> 276postfix/smtpd[19052]: using backwards-compatible default setting 277 <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to accept mail for domain 278 "foo.example.com" 279</pre> 280</blockquote> 281 282<blockquote> 283<pre> 284postfix/smtpd[19052]: using backwards-compatible default setting 285 <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to accept mail for address 286 "user@foo.example.com" 287</pre> 288</blockquote> 289 290<li> <p> Messages about providing ETRN service for a remote domain:</p> 291 292<blockquote> 293<pre> 294postfix/smtpd[19138]: using backwards-compatible default setting 295 <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to flush mail for domain 296 "bar.example.com" 297</pre> 298</blockquote> 299 300<blockquote> 301<pre> 302postfix/smtp[13945]: using backwards-compatible default setting 303 <a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a> to update fast-flush logfile for 304 domain "bar.example.com" 305</pre> 306</blockquote> 307 308</ul> 309 310<p> If Postfix should continue to accept mail for that domain or 311continue to provide ETRN service for that domain, then the system 312administrator should make the backwards-compatible setting 313"<a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydestination">mydestination</a>" permanent in <a href="postconf.5.html">main.cf</a>: </p> 314 315<blockquote> 316<pre> 317# <b>postconf '<a href="postconf.5.html#relay_domains">relay_domains</a>=$<a href="postconf.5.html#mydestination">mydestination</a>'</b> 318# <b>postfix reload</b> 319</pre> 320</blockquote> 321 322<p> Note: quotes are required as indicated above. </p> 323 324<p> Instead of $<a href="postconf.5.html#mydestination">mydestination</a>, it may be better to specify an 325explicit list of domain names. </p> 326 327<h2> <a name="smtputf8_enable"> Using backwards-compatible default 328setting smtputf8_enable=no</a> </h2> 329 330<p> The <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> default value has changed from "no" to "yes. 331With the new "yes" setting, the Postfix SMTP server rejects non-ASCII 332addresses from clients that don't request SMTPUTF8 support, after 333Postfix is updated from an older version. The backwards-compatibility 334safety net is designed to prevent such surprises. </p> 335 336<p> As long as the <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> parameter is left at its implicit 337default value, and the <a href="postconf.5.html#compatibility_level">compatibility_level</a> setting is 338less than 1, Postfix logs a warning each time an SMTP command uses a 339non-ASCII address localpart without requesting SMTPUTF8 support: </p> 340 341<blockquote> 342<pre> 343postfix/smtpd[27560]: using backwards-compatible default setting 344 <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no to accept non-ASCII sender address 345 "??@example.org" from localhost[127.0.0.1] 346</pre> 347</blockquote> 348 349<blockquote> 350<pre> 351postfix/smtpd[27560]: using backwards-compatible default setting 352 <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no to accept non-ASCII recipient address 353 "??@example.com" from localhost[127.0.0.1] 354</pre> 355</blockquote> 356 357<p> If the address should not be rejected, and the client cannot 358be updated to use SMTPUTF8, then the system administrator should 359make the backwards-compatible setting "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = no" permanent 360in <a href="postconf.5.html">main.cf</a>: 361 362<blockquote> 363<pre> 364# <b>postconf <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>=no</b> 365# <b>postfix reload</b> 366</pre> 367</blockquote> 368 369<h2> <a name="turnoff">Turning off the backwards-compatibility safety net</a> </h2> 370 371<p> Backwards compatibility is turned off by updating the 372<a href="postconf.5.html#compatibility_level">compatibility_level</a> setting in <a href="postconf.5.html">main.cf</a>. </p> 373 374<blockquote> 375<pre> 376# <b>postconf <a href="postconf.5.html#compatibility_level">compatibility_level</a>=<i>N</i></b> 377# <b>postfix reload</b> 378</pre> 379</blockquote> 380 381<p> For <i>N</i> specify the number that is logged in your <a href="postfix.1.html">postfix(1)</a> 382warning message: </p> 383 384<blockquote> 385<pre> 386warning: To disable backwards compatibility use "postconf <a href="postconf.5.html#compatibility_level">compatibility_level</a>=<i>N</i>" and "postfix reload" 387</pre> 388</blockquote> 389 390<p> Sites that don't care about backwards compatibility may set 391"<a href="postconf.5.html#compatibility_level">compatibility_level</a> = 9999" at their own risk. </p> 392 393</body> 394 395</html> 396
