postfix-master/rewrite.html

   1 <html>
   2
   3 <head>
   4
   5 <title> Postfix Configuration - Address Manipulation</title>
   6
   7 <META NAME="ROBOTS" CONTENT="NOINDEX,NOFOLLOW">
   8 </head>
   9
  10 <body background="obsolete.gif">
  11
  12 <h1><a href="big-picture.html"><img src="small-picture.gif" width="115" height="45"></a> Postfix Configuration - Address Manipulation</h1>
  13
  14 <hr>
  15
  16 <p> <strong> Note: this web page is no longer maintained. It exists
  17 only to avoid breaking links in web pages that describe earlier
  18 versions of the Postfix mail system. </strong> </p>
  19
  20 <a href="docs.html">Up one level</a> |
  21 <a href="basic.html"> Basic Configuration</a> | <a href="uce.html">UCE
  22 Controls</a> | <a href="rate.html"> Rate Controls</a> | <a
  23 href="resource.html"> Resource Controls</a> | Address Manipulation
  24
  25 <h2> Introduction</h2>
  26
  27 Although the initial Postfix release has no address rewriting
  28 language, it can do quite a bit of address manipulation via table
  29 lookup.  While a message flows through the Postfix system, its
  30 addresses are mangled in the order described in this document.
  31
  32 <p>
  33
  34 Unless indicated otherwise, all parameters described here are in
  35 the <b>main.cf</b> file. If you change parameters of a running
  36 Postfix system, don't forget to issue a <b>postfix reload</b>
  37 command.
  38
  39 <p>
  40
  41 All mail:
  42
  43 <p>
  44
  45 <ul>
  46
  47 <li> <a href="#standard"> Rewrite addresses to standard form</a>
  48
  49 <p>
  50
  51 <li> <a href="#canonical"> Canonical address mapping</a>
  52
  53 <p>
  54
  55 <li> <a href="#masquerade"> Address masquerading</a>
  56
  57 <p>
  58
  59 <li> <a href="#virtual"> Virtual address mapping</a>
  60
  61 <p>
  62
  63 <li> <a href="#transport"> Mail transport switch</a>
  64
  65 <p>
  66
  67 <li> <a href="#relocated"> Relocated users table</a>
  68
  69 </ul>
  70
  71 <p>
  72
  73 Local delivery:
  74
  75 <p>
  76
  77 <ul>
  78
  79 <li> <a href="#aliases"> Alias database</a>
  80
  81 <p>
  82
  83 <li> <a href="#forward"> Per-user .forward files</a>
  84
  85 <p>
  86
  87 <li> <a href="#luser_relay"> Non-existent users</a>
  88
  89 </ul>
  90
  91 <a name="standard"> <h2> Rewrite addresses to standard form</h2>
  92
  93 Before the <a href="cleanup.8.html">cleanup</a> daemon runs an
  94 address through any lookup table, it first rewrites the address to
  95 the standard <i>user@fully.qualified.domain</i> form, by sending
  96 the address to the <a href="trivial-rewrite.8.html">trivial-rewrite</a>
  97 daemon. The purpose of rewriting to standard form is to reduce the
  98 number of entries needed in lookup tables. The Postfix <a
  99 href="trivial-rewrite.8.html">trivial-rewrite </a> program implements
 100 the following hard-coded address manipulations:
 101
 102 <dl>
 103
 104 <dt>Rewrite <i>@hosta,@hostb:user@site</i> to <i>user@site</i>
 105
 106 <dd>The source route feature has been deprecated. Postfix has no
 107 ability to handle such addresses, other than to strip off the source
 108 route.
 109
 110 <p>
 111
 112 <a name="swap_bangpath">
 113
 114 <dt>Rewrite <i>site!user</i> to <i>user@site</i>
 115
 116 <dd> This feature is controlled by the boolean <b>swap_bangpath</b>
 117 parameter (default: <b>yes</b>).  The purpose is to rewrite
 118 <b>UUCP</b>-style addresses to domain style. This is useful only when you
 119 receive mail via <b>UUCP</b>, but it probably does not hurt otherwise.
 120
 121 <p>
 122
 123 <a name="percent_hack">
 124
 125 <dt>Rewrite <i>user%domain</i> to <i>user@domain</i>
 126
 127 <dd> This feature is controlled by the boolean <b>allow_percent_hack</b>
 128 parameter (default: <b>yes</b>). Typically, this is used in order
 129 to deal with monstrosities such as <i>user%domain@otherdomain</i>.
 130
 131 <p>
 132
 133 <a name="append_at_myorigin">
 134
 135 <dt>Rewrite <i>user</i> to <i>user@<a
 136 href="basic.html#myorigin">$myorigin</a></i>
 137
 138 <dd> This feature is controlled by the boolean <b>append_at_myorigin</b>
 139 parameter (default: <b>yes</b>).  The purpose is to get consistent
 140 treatment of <i>user</i> on every machine in <b>$myorigin</b>.
 141
 142 <p>
 143
 144 You probably should never turn off this feature, because a lot of
 145 Postfix components expect that all addresses have the form
 146 <i>user@domain</i>.
 147
 148 <p>
 149
 150 If your machine is not the main machine for <b>$myorigin</b> and
 151 you wish to have some users delivered locally without going via
 152 that main machine, make an entry in the <a href="#virtual">virtual</a>
 153 table that redirects <i>user@$myorigin</i> to <i>user@$myhostname</i>.
 154
 155 <p>
 156
 157 <a name="append_dot_mydomain">
 158
 159 <dt>Rewrite <i>user@host</i> to <i>user@host.<a
 160 href="basic.html#mydomain">$mydomain</a></i>
 161
 162 <dd> This feature is controlled by the boolean <b>append_dot_mydomain</b>
 163 parameter (default: <b>yes</b>).  The purpose is to get consistent
 164 treatment of different forms of the same hostname.
 165
 166 <p>
 167
 168 Some will argue that rewriting <i>host</i> to <i>host.$mydomain</i>
 169 is bad. That is why it can be turned off. Others like the convenience of having
 170 the local domain appended automatically.
 171
 172 <p>
 173
 174 <a name="strip_trailing_dot">
 175
 176 <dt>Rewrite <i>user@site.</i> to <i>user@site</i> (without the
 177 trailing dot).
 178
 179 </dl>
 180
 181 <a name="canonical"> <h2> Canonical address mapping</h2>
 182
 183 Before the <a href="cleanup.8.html">cleanup</a> daemon stores
 184 inbound mail into the <b>incoming</b> queue, it uses the <a
 185 href="canonical.5.html">canonical</a> table to rewrite all addresses
 186 in message envelopes and in message headers, local or remote.  The
 187 mapping is useful to replace login names by <i>Firstname.Lastname</i>
 188 style addresses, or to clean up invalid domains in mail addresses
 189 produced by legacy mail systems.
 190
 191 <p>
 192
 193 Canonical mapping is disabled by default. To enable, edit the <b>
 194 canonical_maps</b> parameter in the <b>main.cf</b> file and
 195 specify one or more lookup tables, separated by whitespace or commas.
 196 For example:
 197
 198 <dl>
 199
 200 <dd><b>canonical_maps = hash:/etc/postfix/canonical</b>
 201
 202 </dl>
 203
 204 <p>
 205
 206 In addition to the canonical maps which are applied to both sender
 207 and recipient addresses, you can specify canonical maps that are
 208 applied only to sender addresses or to recipient addresses. For
 209 example:
 210
 211 <dl>
 212
 213 <dd><b>sender_canonical_maps = hash:/etc/postfix/sender_canonical</b>
 214
 215 <p>
 216
 217 <dd><b>recipient_canonical_maps = hash:/etc/postfix/recipient_canonical</b>
 218
 219 </dl>
 220
 221 <p>
 222
 223 The sender and recipient canonical maps are applied before
 224 the common canonical maps.
 225
 226 <p>
 227
 228 Sender-specific rewriting is useful when you want to rewrite ugly
 229 sender addresses to pretty ones, and still want to be able to
 230 send mail to the those ugly address without creating a mailer loop.
 231
 232 <a name="masquerade"> <h2> Address masquerading</h2>
 233
 234 Address masquerading is a method to hide all hosts inside a domain
 235 behind their mail gateway, and to make it appear as if the mail
 236 comes from the gateway itself, instead of from individual machines.
 237
 238 <p>
 239
 240 Address masquerading is disabled by default. To enable, edit the
 241 <b>masquerade_domains</b> parameter in the <b>main.cf</b> file and
 242 specify one or more domain names separated by whitespace or commas.
 243 The list is processed left to right, and processing stops at the
 244 first match.  Thus,
 245
 246 <blockquote>
 247
 248 <b>masquerade_domains = foo.example.com example.com</b>
 249
 250 </blockquote>
 251
 252 strips any.thing.foo.example.com to foo.example.com, but strips
 253 any.thing.else.example.com to example.com.
 254
 255 <p>
 256
 257 A domain name prefixed with ! means do not masquerade this domain
 258 or its subdomains. Thus,
 259
 260 <blockquote>
 261
 262 <b>masquerade_domains = !foo.example.com example.com</b>
 263
 264 </blockquote>
 265
 266 does not change any.thing.foo.example.com and foo.example.com,
 267 but strips any.thing.else.example.com to example.com.
 268
 269 <p>
 270
 271 The <b>masquerade_exceptions</b> configuration parameter specifies
 272 what user names should not be subjected to address masquerading.
 273 Specify one or more user names separated by whitespace or commas.
 274 For example,
 275
 276 <dl>
 277
 278 <dd><b>masquerade_exceptions = root</b>
 279
 280 </dl>
 281
 282 <p>
 283
 284 By default, Postfix makes no exceptions.
 285
 286 <p>
 287
 288 Subtle point: by default, address masquerading is applied only to
 289 message headers and to envelope sender addresses, but not to envelope
 290 recipients. This allows you to use address masquerading on a mail
 291 gateway machine, while still being able to forward mail from outside
 292 to users on individual machines.
 293
 294 <p>
 295
 296 In order to subject envelope recipient addresses to masquerading,
 297 too, specify (only available with Postfix versions after 20010802):
 298
 299 <dl>
 300
 301 <dd><b>masquerade_classes = envelope_sender, envelope_recipient,
 302 header_sender, header_recipient</b>
 303
 304 </dl>
 305
 306 <p>
 307
 308 If you do this, Postfix will no longer be able to send mail to
 309 individual machines.
 310
 311 <a name="virtual"> <h2> Virtual address aliasing</h2>
 312
 313 After applying the canonical and masquerade mappings, the <a
 314 href="cleanup.8.html">cleanup</a> daemon uses the <a
 315 href="virtual.5.html">virtual alias</a> table to redirect mail for all
 316 recipients, local or remote.  The mapping affects only envelope
 317 recipients; it has no effect on message headers or envelope senders.
 318 Virtual alias lookups are useful to redirect mail for virtual
 319 alias domains to real user mailboxes, and to redirect mail for
 320 domains that no longer exist.  Virtual alias lookups can also be
 321 used to transform <i> Firstname.Lastname </i> back into UNIX login
 322 names, although it seems that local <a href="#aliases">aliases</a>
 323 are a more appropriate vehicle.
 324
 325 <p>
 326
 327 Virtual aliasing is disabled by default. To enable, edit the <b>
 328 virtual_alias_maps</b> parameter in the <b>main.cf</b> file and
 329 specify one or more lookup tables, separated by whitespace or
 330 commas. For example:
 331
 332 <dl>
 333
 334 <dd><b>virtual_alias_maps = hash:/etc/postfix/virtual</b>
 335
 336 </dl>
 337
 338 <p>
 339
 340 Addresses found in virtual alias maps are subjected to another
 341 iteration of virtual aliasing, but are not subjected to canonical
 342 mapping, in order to avoid loops.
 343
 344 <a name="transport"> <h2> Mail transport switch</h2>
 345
 346 Once the address rewriting and resolving daemon has established
 347 the destination of a message, it determines the default delivery
 348 method for that destination. Postfix distinguishes four major
 349 address classes, each with its own default delivery method.
 350
 351 <blockquote>
 352
 353 <table border="1">
 354
 355 <tr><th align="left">Destination matches<th align="left">Default delivery agent <th align="left">Controlling parameter
 356
 357 <tr><td><a href="basic.html#mydestination">$mydestination</a> or
 358 <a href="basic.html#inet_interfaces">$inet_interfaces</a>
 359 <td><a href="local.8.html">local</a>
 360 <td><b>$local_transport</b>
 361
 362 <tr><td><b>$virtual_mailbox_domains</b>
 363 <td><a href="virtual.8.html">virtual</a>
 364 <td><b>$virtual_transport</b>
 365
 366 <tr><td><a href="uce.html#relay_domains">$relay_domains</a>
 367 <td>relay (clone of <a href="smtp.8.html">smtp</a>)
 368 <td><b>$relay_transport</b>
 369
 370 <tr><td>none
 371 <td><a href="smtp.8.html">smtp</a>
 372 <td><b>$default_transport</b>
 373
 374 </table>
 375
 376 </blockquote>
 377
 378 The optional <a href="transport.5.html">transport</a> table overrides
 379 the default message delivery method (this table is used by the
 380 address rewriting and resolving daemon).
 381
 382 The transport table can be used to send mail to specific sites via
 383 <b>UUCP</b>, or to send mail to a really broken mail system that
 384 can handle only one SMTP connection at a time (yes, such systems
 385 exist and people used to pay real money for them).
 386
 387 <p>
 388
 389 Transport table lookups are disabled by default. To enable, edit
 390 the <b>transport_maps</b> parameter in the <b>main.cf</b> file and
 391 specify one or more lookup tables, separated by whitespace or
 392 commas. For example:
 393
 394 <dl>
 395
 396 <dd><b>transport_maps = hash:/etc/postfix/transport</b>
 397
 398 </dl>
 399
 400 <a name="relocated"> <h2> Relocated users table</h2>
 401
 402 Next, the address rewriting and resolving daemon runs each recipient
 403 name through the <a href="relocated.5.html">relocated</a> database.
 404 This table provides information on how to reach users that no longer
 405 have an account, or what to do with mail for entire domains that
 406 no longer exist.  When mail is sent to an address that is listed
 407 in this table, the message is bounced with an informative message.
 408
 409 <p>
 410
 411 Lookups of relocated users are disabled by default. To enable, edit
 412 the <b>relocated_maps</b> parameter in the <b>main.cf</b>
 413 file and specify one or more lookup tables, separated by whitespace
 414 or commas. For example:
 415
 416 <dl>
 417
 418 <dd><b>relocated_maps = hash:/etc/postfix/relocated</b>
 419
 420 </dl>
 421
 422 <a name="aliases"> <h2> Alias database</h2>
 423
 424 When mail is to be delivered locally, the <a href="local.8.html">local</a>
 425 delivery agent runs each local recipient name through the <a
 426 href="aliases.5.html"> aliases</a> database.  The mapping does not
 427 affect addresses in message headers. Local aliases are typically
 428 used to implement distribution lists, or to direct mail for standard
 429 aliases such as <b>postmaster</b> to real people. The table can
 430 also be used to map <i>Firstname.Lastname</i> addresses to login
 431 names.
 432
 433 <p>
 434
 435 Alias lookups are enabled by default. The default configuration
 436 depends on the system environment, but it is typically one of the
 437 following:
 438
 439 <p>
 440
 441 <dl>
 442
 443 <dd> <b>alias_maps = hash:/etc/aliases</b>
 444
 445 <dd> <b>alias_maps = dbm:/etc/aliases, nis:mail.aliases</b>
 446
 447 </dl>
 448
 449 <p>
 450
 451 The path to the alias database file is controlled via the
 452 <b>alias_database</b> configuration parameter. The value is system
 453 dependent. Usually it is one of the following:
 454
 455 <dl>
 456
 457 <dd> <b>alias_database = hash:/etc/aliases</b> (4.4BSD, LINUX)
 458
 459 <dd> <b>alias_database = dbm:/etc/aliases</b> (4.3BSD, SYSV&lt;4)
 460
 461 <dd> <b>alias_database = dbm:/etc/mail/aliases</b> (SYSV4)
 462
 463 </dl>
 464
 465 <p>
 466
 467 For security reasons, deliveries to command and file destinations
 468 are performed with the rights of the alias database owner.  A
 469 default userid, <b>default_privs</b>, is used for deliveries to
 470 commands/files in <i>root</i>-owned aliases.
 471
 472 <a name="forward"> <h2> Per-user .forward files</h2>
 473
 474 Users can control their own mail delivery by specifying destinations
 475 in a file called <b>.forward</b> in their home directories. The
 476 syntax of these files is the same as with system aliases, except
 477 that the lookup key and colon are not present.
 478
 479 <a name="luser_relay"> <h2> Non-existent users</h2>
 480
 481 When the local delivery agent finds that a message recipient does
 482 not exist, the message is normally bounced to the sender ("user
 483 unknown").  Sometimes it is desirable to forward mail for non-existing
 484 recipients to another machine.  For this purpose you can specify
 485 an alternative destination with the <b>luser_relay</b> configuration
 486 parameter.
 487
 488 <p>
 489
 490 Alternatively, mail for non-existent recipients can be delegated
 491 to an entirely different message transport, as specified with the
 492 <b>fallback_transport</b> configuration parameter. For details,
 493 see the <a href="local.8.html"> local</a> delivery agent.
 494
 495 <p>
 496
 497 Note: if you use the <b>luser_relay</b> feature in order to receive
 498 mail for non-UNIX accounts, then you must specify:
 499
 500 <blockquote>
 501 <pre>
 502 <b>local_recipient_maps =</b>
 503 </pre>
 504 </blockquote>
 505
 506 (i.e. empty) in the <b>main.cf</b> file, otherwise the Postfix SMTP
 507 server will reject mail for non-UNIX accounts with "User unknown
 508 in local recipient table".
 509
 510 <p>
 511
 512 <b>luser_relay</b> can specify one address. It is subjected to
 513 <i>$name</i> expansions. The most useful examples are:
 514
 515 <p>
 516
 517 <dl>
 518
 519 <dt><b>$user@other.host</b>
 520
 521 <dd>The bare username, without address extension, is prepended to
 522 <i>@other.host</i>. For example, mail for <i>username+foo</i> is
 523 sent to <i>username@other.host</i>.
 524
 525 <p>
 526
 527 <dt><b>$mailbox@other.host</b>
 528
 529 <dd>The entire original recipient localpart, including address
 530 extension, is prepended to <i>@other.host</i>. For example, mail
 531 for <i>username+foo</i> is sent to <i>username+foo@other.host</i>.
 532
 533 <p>
 534
 535 <dt><b>sysadmin+$user</b>
 536
 537 <dd>The bare username, without address extension, is appended to
 538 <i>sysadmin</i>. For example, mail for <i>username+foo</i> is sent
 539 to <i>sysadmin+username</i>.
 540
 541 <dt><b>sysadmin+$mailbox</b>
 542
 543 <dd>The entire original recipient localpart, including address
 544 extension, is appended to <i>sysadmin</i>. For example, mail for
 545 <i>username+foo</i> is sent to <i>sysadmin+username+foo</i>.
 546
 547
 548 </dl>
 549
 550 <hr>
 551
 552 <a href="docs.html">Up one level</a> |
 553 <a href="basic.html"> Basic Configuration</a> | <a href="uce.html">UCE
 554 Controls</a> | <a href="rate.html"> Rate Controls</a> | <a
 555 href="resource.html"> Resource Controls</a> | Address Manipulation
 556
 557 </body>
 558
 559 </html>