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 Address Rewriting </title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 18Address Rewriting </h1> 19 20<hr> 21 22<h2> <a name="purpose"> Postfix address rewriting purpose </a> </h2> 23 24<p> Address rewriting is at the heart of the Postfix mail system. 25Postfix rewrites addresses for many different purposes. Some are 26merely cosmetic, and some are necessary to deliver correctly 27formatted mail to the correct destination. Examples of 28address rewriting in Postfix are: </p> 29 30<ul> 31 32<li> <p> Transform an incomplete address into a complete address. 33For example, transform "username" into "username@example.com", or 34transform "username@hostname" into "username@hostname.example.com". 35</p> 36 37<li> <p> Replace an address by an equivalent address. For example, 38replace "username@example.com" by "firstname.lastname@example.com" 39when sending mail, and do the reverse transformation when receiving 40mail. </p> 41 42<li> <p> Replace an internal address by an external address. For 43example, replace "username@localdomain.local" by "isp-account@isp.example" 44when sending mail from a home computer to the Internet. 45</p> 46 47<li> <p> Replace an address by multiple addresses. For example, 48replace the address of an alias by the addresses listed under that 49alias. </p> 50 51<li> <p> Determine how and where to deliver mail for a specific 52address. For example, deliver mail for "username@example.com" with 53the smtp(8) delivery agent, to the hosts that are listed in the 54DNS as the mail servers for the domain "example.com". </p> 55 56</ul> 57 58<p> Although Postfix currently has no address rewriting language, 59it can do surprisingly powerful address manipulation via table 60lookup. Postfix typically uses lookup tables with fixed strings 61to map one address to one or multiple addresses, and typically uses 62regular expressions to map multiple addresses to one or multiple 63addresses. Fixed-string lookup tables may be in the form of local 64files, or in the form of NIS, LDAP or SQL databases. The 65DATABASE_README document gives an introduction to Postfix lookup 66tables. </p> 67 68<p> Topics covered in this document: </p> 69 70<ul> 71 72<li> <a href="#william"> To rewrite message headers or not, or to label 73as invalid </a> 74 75<li> <a href="#overview"> Postfix address rewriting overview </a> 76 77<li> <a href="#receiving"> Address rewriting when mail is received</a> 78 79<ul> 80 81<li> <a href="#standard"> Rewrite addresses to standard form</a> 82 83<li> <a href="#canonical"> Canonical address mapping </a> 84 85<li> <a href="#masquerade"> Address masquerading </a> 86 87<li> <a href="#auto_bcc"> Automatic BCC recipients</a> 88 89<li> <a href="#virtual"> Virtual aliasing </a> 90 91</ul> 92 93<li> <a href="#delivering"> Address rewriting when mail is delivered</a> 94 95<ul> 96 97<li> <a href="#resolve"> Resolve address to destination </a> 98 99<li> <a href="#transport"> Mail transport switch </a> 100 101<li> <a href="#relocated"> Relocated users table </a> 102 103</ul> 104 105<li> <a href="#remote"> Address rewriting with remote delivery </a> 106 107<ul> 108 109<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a> 110 111</ul> 112 113<li> <a href="#local"> Address rewriting with local delivery </a> 114 115<ul> 116 117<li> <a href="#aliases"> Local alias database </a> 118 119<li> <a href="#forward"> Local per-user .forward files </a> 120 121<li> <a href="#luser_relay"> Local catch-all address </a> 122 123</ul> 124 125<li> <a href="#debugging"> Debugging your address manipulations </a> 126 127</ul> 128 129<h2> <a name="william"> To rewrite message headers or not, or to label 130as invalid </a> </h2> 131 132<p> Postfix versions 2.1 and earlier always rewrite message header 133addresses, and append Postfix's own domain information to addresses 134that Postfix considers incomplete. While rewriting message header 135addresses is OK for mail with a local origin, it is undesirable 136for remote mail: </p> 137 138<ul> 139 140<li> Message header address rewriting is frowned upon by mail standards, 141 142<li> Appending Postfix's own domain produces incorrect results with 143some incomplete addresses, 144 145<li> Appending Postfix's own domain sometimes creates the appearance 146that spam is sent by local users. 147 148</ul> 149 150<p> Postfix versions 2.2 give you the option to either not rewrite 151message headers from remote SMTP clients at all, or to label 152incomplete addresses in such message headers as invalid. Here is 153how it works: </p> 154 155<ul> 156 157<li> Postfix always rewrites message headers from local SMTP clients 158and from the Postfix sendmail command, and appends its own domain 159to incomplete addresses. The local_header_rewrite_clients parameter 160controls what SMTP clients Postfix considers local (by default, 161only local network interface addresses). 162 163<li> Postfix never rewrites message header addresses from remote 164SMTP clients when the remote_header_rewrite_domain parameter value 165is empty (the default setting). 166 167<li> Otherwise, Postfix rewrites message headers from remote SMTP 168clients, and appends the remote_header_rewrite_domain value to 169incomplete addresses. This feature can be used to append a reserved 170domain such as "domain.invalid", so that incomplete addresses cannot 171be mistaken for local addresses. 172 173</ul> 174 175<h2> <a name="overview"> Postfix address rewriting overview </a> </h2> 176 177<p> The figure below zooms in on those parts of Postfix that are most 178involved with address rewriting activity. See the OVERVIEW document 179for an overview of the complete Postfix architecture. Names followed 180by a number are Postfix daemon programs, while unnumbered names 181represent Postfix queues or internal sources of mail messages. </p> 182 183<blockquote> 184 185<table> 186 187<tr> 188 189<td colspan="2"> </td> 190 191<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(std 192form) </td> 193 194<td colspan="5"> </td> 195 196<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(resolve) 197</td> 198 199</tr> 200 201<tr> 202 203<td colspan="2"> </td> 204 205<td align="center"><table><tr><td align="center"> ^<br> <tt> | 206</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table> 207 208<td colspan="5"> </td> 209 210<td align="center"><table><tr><td align="center"> ^<br> <tt> | 211</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table> 212 213<td colspan="2"> </td> 214 215</tr> 216 217<tr> 218 219<td bgcolor="#f0f0ff" align="center" valign="middle"> smtpd(8) 220</td> 221 222<td rowspan="3" align="center" valign="middle"> <tt> >- </tt> 223</td> 224 225<td rowspan="3" bgcolor="#f0f0ff" align="center"> cleanup(8) </td> 226 227<td rowspan="3" align="center" valign="middle"> <tt> -> </tt> 228</td> 229 230<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a 231href="QSHAPE_README.html#incoming_queue"> incoming </a> </td> 232 233<td rowspan="3" align="center" valign="middle"> <tt> -> </tt> 234</td> 235 236<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a 237href="QSHAPE_README.html#active_queue"> active </a> </td> 238 239<td rowspan="3" align="center" valign="middle"> <tt> -> </tt> 240</td> 241 242<td rowspan="3" bgcolor="#f0f0ff" align="center"> qmgr(8) </td> 243 244<td rowspan="3" align="center" valign="middle"> <tt> -< </tt> 245</td> 246 247<td bgcolor="#f0f0ff" align="center" valign="middle"> 248smtp(8) </td> 249 250</tr> 251 252<tr> 253 254<td bgcolor="#f0f0ff" align="center" valign="middle"> 255qmqpd(8) </td> 256 257<td bgcolor="#f0f0ff" align="center" valign="middle"> lmtp(8) </td> 258 259</tr> 260 261<tr> 262 263<td bgcolor="#f0f0ff" align="center" valign="middle"> pickup(8) 264</td> 265 266<td bgcolor="#f0f0ff" align="center" valign="middle"> local(8) 267</td> 268 269</tr> 270 271<tr> 272 273<td colspan="2"> </td> 274 275<td align="center"> ^<br> <tt> | </tt> </td> 276 277<td colspan="3"> </td> 278 279<td align="center"><table><tr><td align="center"> ^<br> <tt> | 280</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table> 281 282<td colspan="4"> </td> 283 284</tr> 285 286<tr> 287 288<td colspan="2"> </td> 289 290<td align="center"> bounces<br> forwarding<br> notices</td> 291 292<td colspan="3"> </td> 293 294<td bgcolor="#f0f0ff" align="center"> <a 295href="QSHAPE_README.html#deferred_queue"> deferred </a> 296 297<td colspan="2"> </td> 298 299</table> 300 301</blockquote> 302 303<p> The table below summarizes all Postfix address manipulations. 304If you're reading this document for the first time, skip forward 305to "<a href="ADDRESS_REWRITING_README.html#receiving">Address 306rewriting when mail is received</a>". Once you've finished reading 307the remainder of this document, the table will help you to quickly 308find what you need. </p> 309 310<blockquote> 311 312<table border="1"> 313 314<tr> <th nowrap> Address manipulation </th> <th nowrap> Scope </th> 315<th> Daemon </th> <th nowrap> Global turn-on control </th> <th nowrap> Selective 316turn-off control </th> </tr> 317 318<tr> <td> <a href="#standard"> Rewrite addresses to standard form</a> 319</td> <td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> 320<td> append_at_myorigin, append_dot_mydomain, swap_bangpath, 321allow_percent_hack </td> <td> local_header_rewrite_clients, 322remote_header_rewrite_domain </td> </tr> 323 324<tr> <td> <a href="#canonical"> Canonical address mapping </a> </td> 325<td nowrap> all mail </td> <td> cleanup(8) </td> <td> canonical_maps 326</td> <td> receive_override_options, local_header_rewrite_clients, 327remote_header_rewrite_domain </td> </tr> 328 329<tr> <td> <a href="#masquerade"> Address masquerading </a> </td> <td 330nowrap> all mail </td> <td> cleanup(8) </td> <td> masquerade_domains 331</td> <td> receive_override_options, local_header_rewrite_clients, 332remote_header_rewrite_domain </td> </tr> 333 334<tr> <td> <a href="#auto_bcc"> Automatic BCC recipients </a> </td> 335<td nowrap> new mail </td> <td> cleanup(8) </td> <td> always_bcc, 336sender_bcc_maps, recipient_bcc_maps </td> <td> receive_override_options 337</td> </tr> 338 339<tr> <td> <a href="#virtual"> Virtual aliasing </a> </td> <td 340nowrap> all mail </td> <td> cleanup(8) </td> <td> virtual_alias_maps 341</td> <td> receive_override_options </td> </tr> 342 343<tr> <td> <a href="#resolve"> Resolve address to destination </a> 344</td> <td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> 345<td> none </td> <td> none </td> </tr> 346 347<tr> <td> <a href="#transport"> Mail transport switch</a> </td> 348<td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> <td> 349transport_maps </td> <td> none </td> </tr> 350 351<tr> <td> <a href="#relocated"> Relocated users table</a> </td> 352<td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> <td> 353relocated_maps </td> <td> none </td> </tr> 354 355<tr> <td> <a href="#generic"> Generic mapping table </a> </td> <td> 356outgoing SMTP mail </td> <td> smtp(8) </td> <td> smtp_generic_maps 357</td> <td> none </td> </tr> 358 359<tr> <td> <a href="#aliases"> Local alias database</a> </td> <td> 360local mail only </td> <td> local(8) </td> <td> alias_maps </td> <td> none 361</td> </tr> 362 363<tr> <td> <a href="#forward"> Local per-user .forward files</a> 364</td> <td> local mail only </td> <td> local(8) </td> <td> forward_path 365</td> <td> none </td> </tr> 366 367<tr> <td> <a href="#luser_relay"> Local catch-all address</a> </td> 368<td> local mail only </td> <td> local(8) </td> <td> luser_relay </td> <td> 369none </td> </tr> 370 371</table> 372 373</blockquote> 374 375<h2> <a name="receiving"> Address rewriting when mail is received</a> 376</h2> 377 378<p> The cleanup(8) server receives mail from outside of Postfix as 379well as mail from internal sources such as forwarded mail, 380undeliverable mail that is bounced to the sender, and postmaster 381notifications about problems with the mail system. </p> 382 383<p> The cleanup(8) server transforms the sender, recipients and 384message content into a standard form before writing it to an incoming 385queue file. The server cleans up sender and recipient addresses in 386message headers and in the envelope, adds missing message headers 387such as From: or Date: that are required by mail standards, and 388removes message headers such as Bcc: that should not be present. 389The cleanup(8) server delegates the more complex address manipulations 390to the trivial-rewrite(8) server as described later in this document. 391</p> 392 393<p> Address manipulations at this stage are: </p> 394 395<ul> 396 397<li> <a href="#standard"> Rewrite addresses to standard form</a> 398 399<li> <a href="#canonical"> Canonical address mapping</a> 400 401<li> <a href="#masquerade"> Address masquerading</a> 402 403<li> <a href="#auto_bcc"> Automatic BCC recipients</a> 404 405<li> <a href="#virtual"> Virtual aliasing </a> 406 407</ul> 408 409<h3> <a name="standard"> Rewrite addresses to standard form</a> </h3> 410 411<p> Before the cleanup(8) daemon runs an address through any address 412mapping lookup table, it first rewrites the address to the standard 413"user@fully.qualified.domain" form, by sending the address to the 414trivial-rewrite(8) daemon. The purpose of rewriting to standard 415form is to reduce the number of entries needed in lookup tables. 416</p> 417 418<p> The Postfix trivial-rewrite(8) daemon implements the following 419hard-coded address manipulations: </p> 420 421<blockquote> 422 423<dl> 424 425<dt>Rewrite "@hosta,@hostb:user@site" to "user@site"</dt> 426 427<dd> <p> In case you wonder what this is, the address form above 428is called a route address, and specifies that mail for "user@site" 429be delivered via "hosta" and "hostb". Usage of this form has been 430deprecated for a long time. Postfix has no ability to handle route 431addresses, other than to strip off the route part. </p> 432 433<p> NOTE: Postfix versions 2.2 and later rewrite message headers 434from remote SMTP clients only if the client matches the 435local_header_rewrite_clients parameter, or if the 436remote_header_rewrite_domain configuration parameter specifies a 437non-empty value. To get the behavior before Postfix 2.2, specify 438"local_header_rewrite_clients = static:all". </p> </dd> 439 440<dt>Rewrite "site!user" to "user@site" </dt> 441 442<dd> <p> This feature is controlled by the boolean swap_bangpath 443parameter (default: yes). The purpose is to rewrite UUCP-style 444addresses to domain style. This is useful only when you receive 445mail via UUCP, but it probably does not hurt otherwise. </p> 446 447<p> NOTE: Postfix versions 2.2 and later rewrite message headers 448from remote SMTP clients only if the client matches the 449local_header_rewrite_clients parameter, or if the 450remote_header_rewrite_domain configuration parameter specifies a 451non-empty value. To get the behavior before Postfix 2.2, specify 452"local_header_rewrite_clients = static:all". </p> </dd> 453 454<dt>Rewrite "user%domain" to "user@domain"</dt> 455 456<dd> <p> This feature is controlled by the boolean allow_percent_hack 457parameter (default: yes). Typically, this is used in order to deal 458with monstrosities such as "user%domain@otherdomain". </p> 459 460<p> NOTE: Postfix versions 2.2 and later rewrite message headers 461from remote SMTP clients only if the client matches the 462local_header_rewrite_clients parameter, or if the 463remote_header_rewrite_domain configuration parameter specifies a 464non-empty value. To get the behavior before Postfix 2.2, specify 465"local_header_rewrite_clients = static:all". </p> </dd> 466 467<dt> 468 469Rewrite "user" to "user@$myorigin" </dt> 470 471<dd> <p> This feature is controlled by the boolean append_at_myorigin 472parameter (default: yes). You should never turn off this feature, 473because a lot of Postfix components expect that all addresses have 474the form "user@domain". </p> 475 476<p> NOTE: Postfix versions 2.2 and later rewrite message headers 477from remote SMTP clients only if the client matches the 478local_header_rewrite_clients parameter; otherwise they append the 479domain name specified with the remote_header_rewrite_domain 480configuration parameter, if one is specified. To get the behavior 481before Postfix 2.2, specify "local_header_rewrite_clients = 482static:all". </p> 483 484<p> If your machine is not the main machine for $myorigin and you 485wish to have some users delivered locally without going via that 486main machine, make an entry in the <a href="#virtual">virtual 487alias</a> table that redirects "user@$myorigin" to 488"user@$myhostname". See also the "delivering some 489users locally" section in the STANDARD_CONFIGURATION_README 490document. </p> </dd> 491 492<dt> 493 494Rewrite "user@host" to "user@host.$mydomain" </dt> 495 496<dd> <p> This feature is controlled by the boolean append_dot_mydomain 497parameter (default: Postfix ≥ 3.0: no, Postfix < 3.0: yes). The purpose 498is to get consistent treatment of different forms of the same hostname. </p> 499 500<p> NOTE: Postfix versions 2.2 and later rewrite message headers 501from remote SMTP clients only if the client matches the 502local_header_rewrite_clients parameter; otherwise they append the 503domain name specified with the remote_header_rewrite_domain 504configuration parameter, if one is specified. To get the behavior 505before Postfix 2.2, specify "local_header_rewrite_clients = 506static:all". </p> 507 508<p> Some will argue that rewriting "host" to "host.domain" 509is bad. That is why it can be turned off. Others like the convenience 510of having Postfix's own domain appended automatically. </p> </dd> 511 512<dt>Rewrite "user@site." to "user@site" (without the trailing dot).</dt> 513 514<dd> <p> A single trailing dot is silently removed. However, an 515address that ends in multiple dots will be rejected as an invalid 516address. </p> 517 518<p> NOTE: Postfix versions 2.2 and later rewrite message headers 519from remote SMTP clients only if the client matches the 520local_header_rewrite_clients parameter, or if the 521remote_header_rewrite_domain configuration parameter specifies a 522non-empty value. To get the behavior before Postfix 2.2, specify 523"local_header_rewrite_clients = static:all". </p> </dd> 524 525</dl> 526 527</blockquote> 528 529<h3> <a name="canonical"> Canonical address mapping </a> </h3> 530 531<p> The cleanup(8) daemon uses the canonical(5) tables to rewrite 532addresses in message envelopes and in message headers. By default 533all header and envelope addresses are rewritten; this is controlled 534with the canonical_classes configuration parameter. </p> 535 536<p> NOTE: Postfix versions 2.2 and later rewrite message headers 537from remote SMTP clients only if the client matches the 538local_header_rewrite_clients parameter, or if the 539remote_header_rewrite_domain configuration parameter specifies a 540non-empty value. To get the behavior before Postfix 2.2, specify 541"local_header_rewrite_clients = static:all". </p> 542 543<p> Address rewriting is 544done for local and remote addresses. The mapping is useful to 545replace login names by "Firstname.Lastname" style addresses, or to 546clean up invalid domains in mail addresses produced by legacy mail 547systems. </p> 548 549<p> Canonical mapping is disabled by default. To enable, edit the 550canonical_maps parameter in the main.cf file and specify one or 551more lookup tables, separated by whitespace or commas. </p> 552 553<p> Example: </p> 554 555<blockquote> 556<pre> 557/etc/postfix/main.cf: 558 canonical_maps = hash:/etc/postfix/canonical 559 560/etc/postfix/canonical: 561 wietse Wietse.Venema 562</pre> 563</blockquote> 564 565<p> For static mappings as shown above, lookup tables such as hash:, 566ldap:, mysql: or pgsql: are sufficient. For dynamic mappings you 567can use regular expression tables. This requires that you become 568intimately familiar with the ideas expressed in regexp_table(5), 569pcre_table(5) and canonical(5). </p> 570 571<p> In addition to the canonical maps which are applied to both sender 572and recipient addresses, you can specify canonical maps that are 573applied only to sender addresses or to recipient addresses. </p> 574 575<p> Example: </p> 576 577<blockquote> 578<pre> 579/etc/postfix/main.cf: 580 sender_canonical_maps = hash:/etc/postfix/sender_canonical 581 recipient_canonical_maps = hash:/etc/postfix/recipient_canonical 582</pre> 583</blockquote> 584 585<p> The sender and recipient canonical maps are applied before the 586common canonical maps. The sender_canonical_classes and 587recipient_canonical_classes parameters control what addresses are 588subject to sender_canonical_maps and recipient_canonical_maps 589mappings, respectively. </p> 590 591<p> Sender-specific rewriting is useful when you want to rewrite 592ugly sender addresses to pretty ones, and still want to be able to 593send mail to the those ugly address without creating a mailer loop. 594</p> 595 596<p> Canonical mapping can be turned off selectively for mail received 597by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings 598in the master.cf file. This feature is available in Postfix version 5992.1 and later. </p> 600 601<p> Example: </p> 602 603<blockquote> 604<pre> 605/etc/postfix/master.cf: 606 127.0.0.1:10026 inet n - n - - smtpd 607 -o receive_override_options=no_address_mappings 608</pre> 609</blockquote> 610 611<p> Note: do not specify whitespace around the "=" here. </p> 612 613<h3> <a name="masquerade"> Address masquerading </a> </h3> 614 615<p> Address masquerading is a method to hide hosts inside a domain 616behind their mail gateway, and to make it appear as if the mail 617comes from the gateway itself, instead of from individual machines. 618</p> 619 620<p> NOTE: Postfix versions 2.2 and later rewrite message headers 621from remote SMTP clients only if the client matches the 622local_header_rewrite_clients parameter, or if the 623remote_header_rewrite_domain configuration parameter specifies a 624non-empty value. To get the behavior before Postfix 2.2, specify 625"local_header_rewrite_clients = static:all". </p> 626 627<p> Address masquerading is disabled by default, and is implemented 628by the cleanup(8) server. To enable, edit the masquerade_domains 629parameter in the main.cf file and specify one or more domain names 630separated by whitespace or commas. When Postfix tries to masquerade 631a domain, it processes the list from left to right, and processing 632stops at the first match. </p> 633 634<p> Example: </p> 635 636<blockquote> 637<pre> 638/etc/postfix/main.cf: 639 masquerade_domains = foo.example.com example.com 640</pre> 641</blockquote> 642 643<p> strips "any.thing.foo.example.com" to "foo.example.com", but 644strips "any.thing.else.example.com" to "example.com". </p> 645 646<p> A domain name prefixed with "<tt>!</tt>" means do not masquerade 647this domain or its subdomains: </p> 648 649<blockquote> 650<pre> 651/etc/postfix/main.cf: 652 masquerade_domains = !foo.example.com example.com 653</pre> 654</blockquote> 655 656<p> does not change "any.thing.foo.example.com" and "foo.example.com", 657but strips "any.thing.else.example.com" to "example.com". </p> 658 659<p> The masquerade_exceptions configuration parameter specifies 660what user names should not be subjected to address masquerading. 661Specify one or more user names separated by whitespace or commas. 662</p> 663 664<p> Example: </p> 665 666<blockquote> 667<pre> 668/etc/postfix/main.cf: 669 masquerade_exceptions = root 670</pre> 671</blockquote> 672 673<p> By default, Postfix makes no exceptions. </p> 674 675<p> Subtle point: by default, address masquerading is applied only to 676message headers and to envelope sender addresses, but not to envelope 677recipients. This allows you to use address masquerading on a mail 678gateway machine, while still being able to forward mail from outside 679to users on individual machines. </p> 680 681<p> In order to subject envelope recipient addresses to masquerading, 682too, specify (Postfix version 1.1 and later):</p> 683 684<blockquote> 685<pre> 686/etc/postfix/main.cf: 687 masquerade_classes = envelope_sender, envelope_recipient, 688 header_sender, header_recipient 689</pre> 690</blockquote> 691 692<p> If you rewrite the envelope recipient like this, Postfix will 693no longer be able to send mail to individual machines. </p> 694 695<p> Address masquerading can be turned off selectively for mail 696received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf 697settings in the master.cf file. This feature is available in 698Postfix version 2.1 and later. </p> 699 700<p> Example: </p> 701 702<blockquote> 703<pre> 704/etc/postfix/master.cf: 705 127.0.0.1:10026 inet n - n - - smtpd 706 -o receive_override_options=no_address_mappings 707</pre> 708</blockquote> 709 710<p> Note: do not specify whitespace around the "=" here. </p> 711 712<h3> <a name="auto_bcc"> Automatic BCC recipients</a> </h3> 713 714<p> After applying the canonical and masquerade mappings, the 715cleanup(8) daemon can generate optional BCC (blind carbon-copy) 716recipients. Postfix provides three mechanisms: </p> 717 718<blockquote> 719 720<dl> 721 722<dt> always_bcc = address </dt> <dd> Deliver a copy of all mail to 723the specified address. In Postfix versions before 2.1, this feature 724is implemented by smtpd(8), qmqpd(8), or pickup(8). </dd> 725 726<dt> sender_bcc_maps = type:table </dt> <dd> Search the specified 727"type:table" lookup table with the envelope sender address for an 728automatic BCC address. This feature is available in Postfix 2.1 729and later. </dd> 730 731<dt> recipient_bcc_maps = type:table </dt> <dd> Search the specified 732"type:table" lookup table with the envelope recipient address for 733an automatic BCC address. This feature is available in Postfix 2.1 734and later. </dd> 735 736</dl> 737 738</blockquote> 739 740<p> Note: automatic BCC recipients are produced only for new mail. 741To avoid mailer loops, automatic BCC recipients are not generated 742for mail that Postfix forwards internally, nor for mail that Postfix 743generates itself. </p> 744 745<p> Automatic BCC recipients (including always_bcc) can be turned 746off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8), 747by overriding main.cf settings in the master.cf file. This feature 748is available in Postfix version 2.1 and later. </p> 749 750<p> Example: </p> 751 752<blockquote> 753<pre> 754/etc/postfix/master.cf: 755 127.0.0.1:10026 inet n - n - - smtpd 756 -o receive_override_options=no_address_mappings 757</pre> 758</blockquote> 759 760<p> Note: do not specify whitespace around the "=" here. </p> 761 762<h3> <a name="virtual"> Virtual aliasing </a> </h3> 763 764<p> Before writing the recipients to the queue file, the cleanup(8) 765daemon uses the optional virtual(5) alias tables to redirect mail 766for recipients. The mapping affects only envelope recipient 767addresses; it has no effect on message headers or envelope sender 768addresses. Virtual alias lookups are useful to redirect mail for 769virtual alias domains to real user mailboxes, and to redirect mail 770for domains that no longer exist. Virtual alias lookups can also 771be used to transform " Firstname.Lastname " back into UNIX login 772names, although it seems that local <a href="#aliases">aliases</a> 773may be a more appropriate vehicle. See the VIRTUAL_README document 774for an overview of methods to host virtual domains with Postfix. 775</p> 776 777<p> Virtual aliasing is disabled by default. To enable, edit the 778virtual_alias_maps parameter in the main.cf file and 779specify one or more lookup tables, separated by whitespace or 780commas. </p> 781 782<p> Example: </p> 783 784<blockquote> 785<pre> 786/etc/postfix/main.cf: 787 virtual_alias_maps = hash:/etc/postfix/virtual 788 789/etc/postfix/virtual: 790 Wietse.Venema wietse 791</pre> 792</blockquote> 793 794<p> Addresses found in virtual alias maps are subjected to another 795iteration of virtual aliasing, but are not subjected to canonical 796mapping, in order to avoid loops. </p> 797 798<p> For static mappings as shown above, lookup tables such as hash:, 799ldap:, mysql: or pgsql: are sufficient. For dynamic mappings you 800can use regular expression tables. This requires that you become 801intimately familiar with the ideas expressed in regexp_table(5), 802pcre_table(5) and virtual(5). </p> 803 804<p> Virtual aliasing can be turned off selectively for mail received 805by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings 806in the master.cf file. This feature is available in Postfix version 8072.1 and later. </p> 808 809<p> Example: </p> 810 811<blockquote> 812<pre> 813/etc/postfix/master.cf: 814 127.0.0.1:10026 inet n - n - - smtpd 815 -o receive_override_options=no_address_mappings 816</pre> 817</blockquote> 818 819<p> Note: do not specify whitespace around the "=" here. </p> 820 821<p> At this point the message is ready to be stored into the 822Postfix incoming queue. </p> 823 824<h2> <a name="delivering"> Address rewriting when mail is delivered</a> </h2> 825 826<p> The Postfix queue manager sorts mail according to its destination 827and gives it to Postfix delivery agents such as local(8), smtp(8), 828or lmtp(8). Just like the cleanup(8) server, the Postfix queue 829manager delegates the more complex address manipulations to the 830trivial-rewrite(8) server. </p> 831 832<p> Address manipulations at this stage are: </p> 833 834<ul> 835 836<li> <a href="#resolve"> Resolve address to destination </a> 837 838<li> <a href="#transport"> Mail transport switch</a> 839 840<li> <a href="#relocated"> Relocated users table</a> 841 842</ul> 843 844<p> Each Postfix delivery agent tries to deliver the mail to its 845destination, while encapsulating the sender, recipients, and message 846content according to the rules of the SMTP, LMTP, etc. protocol. 847When mail cannot be delivered, it is either returned to the sender 848or moved to the deferred queue and tried again later. </p> 849 850<p> <a name="remote">Address</a> manipulations when mail is delivered 851via the smtp(8) delivery agent: </p> 852 853<ul> 854 855<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a> 856 857</ul> 858 859<p> <a name="local">Address</a> manipulations when mail is delivered 860via the local(8) delivery agent: </p> 861 862<ul> 863 864<li> <a href="#aliases"> Local alias database</a> 865 866<li> <a href="#forward"> Local per-user .forward files</a> 867 868<li> <a href="#luser_relay"> Local catch-all address</a> 869 870</ul> 871 872<p> The remainder of this document presents each address manipulation 873step in more detail, with specific examples or with pointers to 874documentation with examples. </p> 875 876<h3> <a name="resolve"> Resolve address to destination </a> </h3> 877 878<p> The Postfix qmgr(8) queue manager selects new mail from the 879incoming queue or old mail from the deferred queue, and asks the 880trivial-rewrite(8) address rewriting and resolving daemon where it 881should be delivered. </p> 882 883<p> As of version 2.0, Postfix distinguishes four major address 884classes. Each class has its own list of domain names, and each 885class has its own default delivery method, as shown in the table 886below. See the ADDRESS_CLASS_README document for the fine details. 887Postfix versions before 2.0 only distinguish between local delivery 888and everything else. </p> 889 890<blockquote> 891 892<table border="1"> 893 894<tr><th align="left">Destination domain list </th> <th 895align="left">Default delivery method </th> <th>Availability 896</th> </tr> 897 898<tr><td>$mydestination, $inet_interfaces, $proxy_interfaces </td> 899<td>$local_transport </td> <td>Postfix 1.0</td></tr> 900 901<tr><td>$virtual_mailbox_domains </td> <td>$virtual_transport </td> 902<td>Postfix 2.0</td> </tr> 903 904<tr><td>$relay_domains </td> <td>$relay_transport </td> <td>Postfix 9052.0</td> </tr> 906 907<tr><td>none </td> <td>$default_transport </td> <td>Postfix 1.0</td> 908</tr> 909 910</table> 911 912</blockquote> 913 914<h3> <a name="transport"> Mail transport switch </a> </h3> 915 916<p> Once the trivial-rewrite(8) daemon has determined a default 917delivery method it searches the optional transport(5) table for 918information that overrides the message destination and/or delivery 919method. Typical use of the transport(5) table is to send mail to 920a system 921that is not connected to the Internet, or to use a special SMTP 922client configuration for destinations that have special requirements. 923See, for example, the STANDARD_CONFIGURATION_README and UUCP_README 924documents, and the examples in the transport(5) manual page. </p> 925 926<p> Transport table lookups are disabled by default. To enable, 927edit the transport_maps parameter in the main.cf file and specify 928one or more lookup tables, separated by whitespace or commas. </p> 929 930<p> Example: </p> 931 932<blockquote> 933<pre> 934/etc/postfix/main.cf: 935 transport_maps = hash:/etc/postfix/transport 936</pre> 937</blockquote> 938 939<h3> <a name="relocated"> Relocated users table </a> </h3> 940 941<p> Next, the trivial-rewrite(8) address rewriting and resolving 942daemon runs each recipient through the relocated(5) database. This 943table provides information on how to reach users that no longer 944have an account, or what to do with mail for entire domains that 945no longer exist. When mail is sent to an address that is listed 946in this table, the message is returned to the sender with an 947informative message. </p> 948 949<p> The relocated(5) database is searched after transport(5) 950table lookups, in anticipation of transport(5) tables that 951can replace one recipient address by a different one. </p> 952 953<p> Lookups of relocated users are disabled by default. To enable, 954edit the relocated_maps parameter in the main.cf file and specify 955one or more lookup tables, separated by whitespace or commas. </p> 956 957<p> Example: </p> 958 959<blockquote> 960<pre> 961/etc/postfix/main.cf: 962 relocated_maps = hash:/etc/postfix/relocated 963 964/etc/postfix/relocated: 965 username@example.com otheruser@elsewhere.tld 966</pre> 967</blockquote> 968 969<p> As of Postfix version 2, mail for a relocated user will be 970rejected by the SMTP server with the reason "user has moved to 971otheruser@elsewhere.tld". Older Postfix versions will receive the 972mail first, and then return it to the sender as undeliverable, with 973the same reason. </p> 974 975<h3> <a name="generic"> Generic mapping for outgoing SMTP mail </a> </h3> 976 977<p> Some hosts have no valid Internet domain name, and instead use 978a name such as <i>localdomain.local</i>. This can be a problem when 979you want to send mail over the Internet, because many mail servers 980reject mail addresses with invalid domain names. </p> 981 982<p> With the smtp_generic_maps parameter you can specify generic(5) 983lookup tables that replace local mail addresses by valid Internet 984addresses when mail leaves the machine via SMTP. The generic(5) 985mapping replaces envelope and header addresses, and is non-recursive. 986It does not happen when you send mail between addresses on the 987local machine. </p> 988 989<p> This feature is available in Postfix version 2.2 and later.</p> 990 991<p> Example: </p> 992 993<blockquote> 994<pre> 995/etc/postfix/main.cf: 996 smtp_generic_maps = hash:/etc/postfix/generic 997 998/etc/postfix/generic: 999 his@localdomain.local hisaccount@hisisp.example 1000 her@localdomain.local heraccount@herisp.example 1001 @localdomain.local hisaccount+local@hisisp.example 1002</pre> 1003</blockquote> 1004 1005<p> When mail is sent to a remote host via SMTP, this replaces 1006<i>his@localdomain.local</i> by his ISP mail address, replaces 1007<i>her@localdomain.local</i> by her ISP mail address, and replaces 1008other local addresses by his ISP account, with an address extension 1009of +<i>local</i> (this example assumes that the ISP supports "+" 1010style address extensions). </p> 1011 1012<h3> <a name="aliases"> Local alias database </a> </h3> 1013 1014<p> When mail is to be delivered locally, the local(8) delivery 1015agent runs each local recipient name through the aliases(5) database. 1016The mapping does not affect addresses in message headers. Local 1017aliases are typically used to implement distribution lists, or to 1018direct mail for standard aliases such as postmaster to real people. 1019The table can also be used to map "Firstname.Lastname" addresses 1020to login names. </p> 1021 1022<p> Alias lookups are enabled by default. The default configuration 1023depends on the operating system environment, but it is typically 1024one of the following: </p> 1025 1026<blockquote> 1027<pre> 1028/etc/postfix/main.cf: 1029 alias_maps = hash:/etc/aliases 1030 alias_maps = dbm:/etc/aliases, nis:mail.aliases 1031</pre> 1032</blockquote> 1033 1034<p> The pathname of the alias database file is controlled with the 1035alias_database configuration parameter. The value is system dependent. 1036Usually it is one of the following: </p> 1037 1038<blockquote> 1039<pre> 1040/etc/postfix/main.cf: 1041 alias_database = hash:/etc/aliases (4.4BSD, LINUX) 1042 alias_database = dbm:/etc/aliases (4.3BSD, SYSV<4) 1043 alias_database = dbm:/etc/mail/aliases (SYSV4) 1044</pre> 1045</blockquote> 1046 1047<p> An aliases(5) file can specify that mail should be delivered 1048to a local file, or to a command that receives the message in the 1049standard input stream. For security reasons, deliveries to command 1050and file destinations are performed with the rights of the alias 1051database owner. A default userid, default_privs, is used for 1052deliveries to commands or files in "root"-owned aliases. </p> 1053 1054<h3> <a name="forward"> Local per-user .forward files </a> </h3> 1055 1056<p> With delivery via the local(8) delivery agent, users can control 1057their own mail delivery by specifying destinations in a file called 1058.forward in their home directories. The syntax of these files is 1059the same as with the local aliases(5) file, except that the left-hand 1060side of the alias (lookup key and colon) are not present. </p> 1061 1062<h3> <a name="luser_relay"> Local catch-all address </a> </h3> 1063 1064<p> When the local(8) delivery agent finds that a message recipient 1065does not exist, the message is normally returned to the sender ("user 1066unknown"). Sometimes it is desirable to forward mail for non-existing 1067recipients to another machine. For this purpose you can specify 1068an alternative destination with the luser_relay configuration 1069parameter. </p> 1070 1071<p> Alternatively, mail for non-existent recipients can be delegated 1072to an entirely different message transport, as specified with the 1073fallback_transport configuration parameter. For details, see the 1074local(8) delivery agent documentation. </p> 1075 1076<p> Note: if you use the luser_relay feature in order to receive 1077mail for non-UNIX accounts, then you must specify: </p> 1078 1079<blockquote> 1080<pre> 1081/etc/postfix/main.cf: 1082 local_recipient_maps = 1083</pre> 1084</blockquote> 1085 1086<p> (i.e. empty) in the main.cf file, otherwise the Postfix SMTP 1087server will reject mail for non-UNIX accounts with "User unknown 1088in local recipient table". See the LOCAL_RECIPIENT_README file 1089for more information on this. 1090</p> 1091 1092<p> luser_relay can specify one address. It is subjected to "$name" 1093expansions. Examples: </p> 1094 1095<blockquote> 1096 1097<dl> 1098 1099<dt>$user@other.host </dt> 1100 1101<dd> <p> The bare username, without address extension, is prepended 1102to "@other.host". For example, mail for "username+foo" is sent to 1103"username@other.host". </p> </dd> 1104 1105<dt>$local@other.host </dt> 1106 1107<dd> <p> The entire original recipient localpart, including address 1108extension, is prepended to "@other.host". For example, mail for 1109"username+foo" is sent to "username+foo@other.host". </p> </dd> 1110 1111<dt>sysadmin+$user </dt> 1112 1113<dd> <p> The bare username, without address extension, is appended 1114to "sysadmin". For example, mail for "username+foo" is sent to 1115"sysadmin+username". </p> </dd> 1116 1117<dt>sysadmin+$local </dt> 1118 1119<dd> <p> The entire original recipient localpart, including address 1120extension, is appended to "sysadmin". For example, mail for 1121"username+foo" is sent to "sysadmin+username+foo". </p> </dd> 1122 1123</dl> 1124 1125</blockquote> 1126 1127<h2> <a name="debugging"> Debugging your address manipulations </a> </h2> 1128 1129<p> Postfix version 2.1 and later can 1130produce mail delivery reports for debugging purposes. These reports 1131not only show sender/recipient addresses after address rewriting 1132and alias expansion or forwarding, they also show information about 1133delivery to mailbox, delivery to non-Postfix command, responses 1134from remote SMTP servers, and so on. </p> 1135 1136<p> Postfix can produce two types of mail delivery reports for 1137debugging: </p> 1138 1139<ul> 1140 1141<li> <p> What-if: report what would happen, but do not actually 1142deliver mail. This mode of operation is requested with: </p> 1143 1144<pre> 1145$ <b>/usr/sbin/sendmail -bv address...</b> 1146Mail Delivery Status Report will be mailed to <your login name>. 1147</pre> 1148 1149<li> <p> What happened: deliver mail and report successes and/or 1150failures, including replies from remote SMTP servers. This mode 1151of operation is requested with: </p> 1152 1153<pre> 1154$ <b>/usr/sbin/sendmail -v address...</b> 1155Mail Delivery Status Report will be mailed to <your login name>. 1156</pre> 1157 1158</ul> 1159 1160<p> These reports contain information that is generated by Postfix 1161delivery agents. Since these run as daemon processes and do not 1162interact with users directly, the result is sent as mail to the 1163sender of the test message. The format of these reports is practically 1164identical to that of ordinary non-delivery notifications. </p> 1165 1166<p> As an example, below is the delivery report that is produced 1167with the command "sendmail -bv postfix-users@postfix.org". The 1168first part of the report contains human-readable text. In this 1169case, mail would be delivered via mail.cloud9.net, and the SMTP 1170server replies with "250 Ok". Other reports may show delivery 1171to mailbox, or delivery to non-Postfix command. </p> 1172 1173<blockquote> 1174<pre> 1175Content-Description: Notification 1176Content-Type: text/plain 1177 1178This is the mail system at host spike.porcupine.org. 1179 1180Enclosed is the mail delivery report that you requested. 1181 1182 The mail system 1183 1184<postfix-users@postfix.org>: delivery via mail.cloud9.net[168.100.1.4]: 250 2.1.5 Ok 1185</pre> 1186</blockquote> 1187 1188<p> The second part of the report is in machine-readable form, and 1189includes the following information: </p> 1190 1191<ul> 1192 1193<li> The envelope sender address (wietse@porcupine.org). 1194 1195<li> The envelope recipient address (postfix-users@postfix.org). 1196If the recipient address was changed by Postfix then Postfix also 1197includes the original recipient address. 1198 1199<li> The delivery status. 1200 1201</ul> 1202 1203<p> Some details depend on Postfix version. The example below is 1204for Postfix version 2.3 and later. </p> 1205 1206<blockquote> 1207<pre> 1208Content-Description: Delivery report 1209Content-Type: message/delivery-status 1210 1211Reporting-MTA: dns; spike.porcupine.org 1212X-Postfix-Queue-ID: 84863BC0E5 1213X-Postfix-Sender: rfc822; wietse@porcupine.org 1214Arrival-Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST) 1215 1216Final-Recipient: rfc822; postfix-users@postfix.org 1217Action: deliverable 1218Status: 2.1.5 1219Remote-MTA: dns; mail.cloud9.net 1220Diagnostic-Code: smtp; 250 2.1.5 Ok 1221</pre> 1222</blockquote> 1223 1224<p> The third part of the report contains the message that Postfix 1225would have delivered, including From: and To: message headers, so 1226that you can see any effects of address rewriting on those. Mail 1227submitted with "sendmail -bv" has no body content so none is shown 1228in the example below. </p> 1229 1230<blockquote> 1231<pre> 1232Content-Description: Message 1233Content-Type: message/rfc822 1234 1235Received: by spike.porcupine.org (Postfix, from userid 1001) 1236 id 84863BC0E5; Sun, 26 Nov 2006 17:01:01 -0500 (EST) 1237Subject: probe 1238To: postfix-users@postfix.org 1239Message-Id: <20061126220101.84863BC0E5@spike.porcupine.org> 1240Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST) 1241From: wietse@porcupine.org (Wietse Venema) 1242</pre> 1243</blockquote> 1244 1245</body> 1246 1247</html> 1248
