postfix-master/ADDRESS_REWRITING_README.html

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