summaryrefslogtreecommitdiffstats
path: root/README_FILES/ADDRESS_REWRITING_README
blob: a0ccc20400166197f3aba505176bd1c4a3664729 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
PPoossttffiixx AAddddrreessss RReewwrriittiinngg

-------------------------------------------------------------------------------

PPoossttffiixx aaddddrreessss rreewwrriittiinngg ppuurrppoossee

Address rewriting is at the heart of the Postfix mail system. Postfix rewrites
addresses for many different purposes. Some are merely cosmetic, and some are
necessary to deliver correctly formatted mail to the correct destination.
Examples of address rewriting in Postfix are:

  * Transform an incomplete address into a complete address. For example,
    transform "username" into "username@example.com", or transform
    "username@hostname" into "username@hostname.example.com".

  * Replace an address by an equivalent address. For example, replace
    "username@example.com" by "firstname.lastname@example.com" when sending
    mail, and do the reverse transformation when receiving mail.

  * Replace an internal address by an external address. For example, replace
    "username@localdomain.local" by "isp-account@isp.example" when sending mail
    from a home computer to the Internet.

  * Replace an address by multiple addresses. For example, replace the address
    of an alias by the addresses listed under that alias.

  * Determine how and where to deliver mail for a specific address. For
    example, deliver mail for "username@example.com" with the smtp(8) delivery
    agent, to the hosts that are listed in the DNS as the mail servers for the
    domain "example.com".

Although Postfix currently has no address rewriting language, it can do
surprisingly powerful address manipulation via table lookup. Postfix typically
uses lookup tables with fixed strings to map one address to one or multiple
addresses, and typically uses regular expressions to map multiple addresses to
one or multiple addresses. Fixed-string lookup tables may be in the form of
local files, or in the form of NIS, LDAP or SQL databases. The DATABASE_README
document gives an introduction to Postfix lookup tables.

Topics covered in this document:

  * To rewrite message headers or not, or to label as invalid
  * Postfix address rewriting overview
  * Address rewriting when mail is received

      o Rewrite addresses to standard form
      o Canonical address mapping
      o Address masquerading
      o Automatic BCC recipients
      o Virtual aliasing

  * Address rewriting when mail is delivered

      o Resolve address to destination
      o Mail transport switch
      o Relocated users table

  * Address rewriting with remote delivery

      o Generic mapping for outgoing SMTP mail

  * Address rewriting with local delivery

      o Local alias database
      o Local per-user .forward files
      o Local catch-all address

  * Debugging your address manipulations

TToo rreewwrriittee mmeessssaaggee hheeaaddeerrss oorr nnoott,, oorr ttoo llaabbeell aass iinnvvaalliidd

Postfix versions 2.1 and earlier always rewrite message header addresses, and
append Postfix's own domain information to addresses that Postfix considers
incomplete. While rewriting message header addresses is OK for mail with a
local origin, it is undesirable for remote mail:

  * Message header address rewriting is frowned upon by mail standards,
  * Appending Postfix's own domain produces incorrect results with some
    incomplete addresses,
  * Appending Postfix's own domain sometimes creates the appearance that spam
    is sent by local users.

Postfix versions 2.2 give you the option to either not rewrite message headers
from remote SMTP clients at all, or to label incomplete addresses in such
message headers as invalid. Here is how it works:

  * Postfix always rewrites message headers from local SMTP clients and from
    the Postfix sendmail command, and appends its own domain to incomplete
    addresses. The local_header_rewrite_clients parameter controls what SMTP
    clients Postfix considers local (by default, only local network interface
    addresses).
  * Postfix never rewrites message header addresses from remote SMTP clients
    when the remote_header_rewrite_domain parameter value is empty (the default
    setting).
  * Otherwise, Postfix rewrites message headers from remote SMTP clients, and
    appends the remote_header_rewrite_domain value to incomplete addresses.
    This feature can be used to append a reserved domain such as
    "domain.invalid", so that incomplete addresses cannot be mistaken for local
    addresses.

PPoossttffiixx aaddddrreessss rreewwrriittiinngg oovveerrvviieeww

The figure below zooms in on those parts of Postfix that are most involved with
address rewriting activity. See the OVERVIEW document for an overview of the
complete Postfix architecture. Names followed by a number are Postfix daemon
programs, while unnumbered names represent Postfix queues or internal sources
of mail messages.

                  trivial-                              trivial-
                 rewrite(8)                            rewrite(8)
                 (std form)                            (resolve)

                      ^ |                                   ^ |
                      | v                                   | v

    smtpd(8)                                                         smtp(8)

    qmqpd(8)  >- cleanup(8) -> incoming ->  active  ->   qmgr(8)  -< lmtp(8)

    pickup(8)                                                        local(8)

                       ^                      ^ |
                       |                      | v

                  bounces
                 forwarding                deferred
                  notices

The table below summarizes all Postfix address manipulations. If you're reading
this document for the first time, skip forward to "Address rewriting when mail
is received". Once you've finished reading the remainder of this document, the
table will help you to quickly find what you need.

     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
    |AAddddrreessss     |SSccooppee   |DDaaeemmoonn  |GGlloobbaall ttuurrnn--oonn      |SSeelleeccttiivvee ttuurrnn--ooffff ccoonnttrrooll   |
    |mmaanniippuullaattiioonn|        |        |ccoonnttrrooll             |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Rewrite     |        |trivial-|append_at_myorigin, |                             |
    |addresses to|all mail|rewrite |append_dot_mydomain,|local_header_rewrite_clients,|
    |standard    |        |(8)     |swap_bangpath,      |remote_header_rewrite_domain |
    |form        |        |        |allow_percent_hack  |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Canonical   |        |cleanup |                    |receive_override_options,    |
    |address     |all mail|(8)     |canonical_maps      |local_header_rewrite_clients,|
    |mapping     |        |        |                    |remote_header_rewrite_domain |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Address     |        |cleanup |                    |receive_override_options,    |
    |masquerading|all mail|(8)     |masquerade_domains  |local_header_rewrite_clients,|
    |            |        |        |                    |remote_header_rewrite_domain |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Automatic   |        |cleanup |always_bcc,         |                             |
    |BCC         |new mail|(8)     |sender_bcc_maps,    |receive_override_options     |
    |recipients  |        |        |recipient_bcc_maps  |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Virtual     |all mail|cleanup |virtual_alias_maps  |receive_override_options     |
    |aliasing    |        |(8)     |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Resolve     |        |trivial-|                    |                             |
    |address to  |all mail|rewrite |none                |none                         |
    |destination |        |(8)     |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Mail        |        |trivial-|                    |                             |
    |transport   |all mail|rewrite |transport_maps      |none                         |
    |switch      |        |(8)     |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Relocated   |        |trivial-|                    |                             |
    |users table |all mail|rewrite |relocated_maps      |none                         |
    |            |        |(8)     |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Generic     |outgoing|        |                    |                             |
    |mapping     |SMTP    |smtp(8) |smtp_generic_maps   |none                         |
    |table       |mail    |        |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Local alias |local   |        |                    |                             |
    |database    |mail    |local(8)|alias_maps          |none                         |
    |            |only    |        |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Local per-  |local   |        |                    |                             |
    |user        |mail    |local(8)|forward_path        |none                         |
    |.forward    |only    |        |                    |                             |
    |files       |        |        |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |Local catch-|local   |        |                    |                             |
    |all address |mail    |local(8)|luser_relay         |none                         |
    |            |only    |        |                    |                             |
    |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |

AAddddrreessss rreewwrriittiinngg wwhheenn mmaaiill iiss rreecceeiivveedd

The cleanup(8) server receives mail from outside of Postfix as well as mail
from internal sources such as forwarded mail, undeliverable mail that is
bounced to the sender, and postmaster notifications about problems with the
mail system.

The cleanup(8) server transforms the sender, recipients and message content
into a standard form before writing it to an incoming queue file. The server
cleans up sender and recipient addresses in message headers and in the
envelope, adds missing message headers such as From: or Date: that are required
by mail standards, and removes message headers such as Bcc: that should not be
present. The cleanup(8) server delegates the more complex address manipulations
to the trivial-rewrite(8) server as described later in this document.

Address manipulations at this stage are:

  * Rewrite addresses to standard form
  * Canonical address mapping
  * Address masquerading
  * Automatic BCC recipients
  * Virtual aliasing

RReewwrriittee aaddddrreesssseess ttoo ssttaannddaarrdd ffoorrmm

Before the cleanup(8) daemon runs an address through any address mapping lookup
table, it first rewrites the address to the standard
"user@fully.qualified.domain" form, by sending the address to the trivial-
rewrite(8) daemon. The purpose of rewriting to standard form is to reduce the
number of entries needed in lookup tables.

The Postfix trivial-rewrite(8) daemon implements the following hard-coded
address manipulations:

    Rewrite "@hosta,@hostb:user@site" to "user@site"
        In case you wonder what this is, the address form above is called a
        route address, and specifies that mail for "user@site" be delivered via
        "hosta" and "hostb". Usage of this form has been deprecated for a long
        time. Postfix has no ability to handle route addresses, other than to
        strip off the route part.

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter, or if the
        remote_header_rewrite_domain configuration parameter specifies a non-
        empty value. To get the behavior before Postfix 2.2, specify
        "local_header_rewrite_clients = static:all".

    Rewrite "site!user" to "user@site"
        This feature is controlled by the boolean swap_bangpath parameter
        (default: yes). The purpose is to rewrite UUCP-style addresses to
        domain style. This is useful only when you receive mail via UUCP, but
        it probably does not hurt otherwise.

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter, or if the
        remote_header_rewrite_domain configuration parameter specifies a non-
        empty value. To get the behavior before Postfix 2.2, specify
        "local_header_rewrite_clients = static:all".

    Rewrite "user%domain" to "user@domain"
        This feature is controlled by the boolean allow_percent_hack parameter
        (default: yes). Typically, this is used in order to deal with
        monstrosities such as "user%domain@otherdomain".

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter, or if the
        remote_header_rewrite_domain configuration parameter specifies a non-
        empty value. To get the behavior before Postfix 2.2, specify
        "local_header_rewrite_clients = static:all".

    Rewrite "user" to "user@$myorigin"
        This feature is controlled by the boolean append_at_myorigin parameter
        (default: yes). You should never turn off this feature, because a lot
        of Postfix components expect that all addresses have the form
        "user@domain".

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter; otherwise they append the
        domain name specified with the remote_header_rewrite_domain
        configuration parameter, if one is specified. To get the behavior
        before Postfix 2.2, specify "local_header_rewrite_clients = static:
        all".

        If your machine is not the main machine for $myorigin and you wish to
        have some users delivered locally without going via that main machine,
        make an entry in the virtual alias table that redirects
        "user@$myorigin" to "user@$myhostname". See also the "delivering some
        users locally" section in the STANDARD_CONFIGURATION_README document.

    Rewrite "user@host" to "user@host.$mydomain"
        This feature is controlled by the boolean append_dot_mydomain parameter
        (default: yes). The purpose is to get consistent treatment of different
        forms of the same hostname.

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter; otherwise they append the
        domain name specified with the remote_header_rewrite_domain
        configuration parameter, if one is specified. To get the behavior
        before Postfix 2.2, specify "local_header_rewrite_clients = static:
        all".

        Some will argue that rewriting "host" to "host.domain" is bad. That is
        why it can be turned off. Others like the convenience of having
        Postfix's own domain appended automatically.

    Rewrite "user@site." to "user@site" (without the trailing dot).
        A single trailing dot is silently removed. However, an address that
        ends in multiple dots will be rejected as an invalid address.

        NOTE: Postfix versions 2.2 and later rewrite message headers from
        remote SMTP clients only if the client matches the
        local_header_rewrite_clients parameter, or if the
        remote_header_rewrite_domain configuration parameter specifies a non-
        empty value. To get the behavior before Postfix 2.2, specify
        "local_header_rewrite_clients = static:all".

CCaannoonniiccaall aaddddrreessss mmaappppiinngg

The cleanup(8) daemon uses the canonical(5) tables to rewrite addresses in
message envelopes and in message headers. By default all header and envelope
addresses are rewritten; this is controlled with the canonical_classes
configuration parameter.

NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP
clients only if the client matches the local_header_rewrite_clients parameter,
or if the remote_header_rewrite_domain configuration parameter specifies a non-
empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".

Address rewriting is done for local and remote addresses. The mapping is useful
to replace login names by "Firstname.Lastname" style addresses, or to clean up
invalid domains in mail addresses produced by legacy mail systems.

Canonical mapping is disabled by default. To enable, edit the canonical_maps
parameter in the main.cf file and specify one or more lookup tables, separated
by whitespace or commas.

Example:

    /etc/postfix/main.cf:
        canonical_maps = hash:/etc/postfix/canonical

    /etc/postfix/canonical:
        wietse        Wietse.Venema

For static mappings as shown above, lookup tables such as hash:, ldap:, mysql:
or pgsql: are sufficient. For dynamic mappings you can use regular expression
tables. This requires that you become intimately familiar with the ideas
expressed in regexp_table(5), pcre_table(5) and canonical(5).

In addition to the canonical maps which are applied to both sender and
recipient addresses, you can specify canonical maps that are applied only to
sender addresses or to recipient addresses.

Example:

    /etc/postfix/main.cf:
        sender_canonical_maps = hash:/etc/postfix/sender_canonical
        recipient_canonical_maps = hash:/etc/postfix/recipient_canonical

The sender and recipient canonical maps are applied before the common canonical
maps. The sender_canonical_classes and recipient_canonical_classes parameters
control what addresses are subject to sender_canonical_maps and
recipient_canonical_maps mappings, respectively.

Sender-specific rewriting is useful when you want to rewrite ugly sender
addresses to pretty ones, and still want to be able to send mail to the those
ugly address without creating a mailer loop.

Canonical mapping can be turned off selectively for mail received by smtpd(8),
qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file.
This feature is available in Postfix version 2.1 and later.

Example:

    /etc/postfix/master.cf:
        127.0.0.1:10026    inet  n      -      n      -      -     smtpd
            -o receive_override_options=no_address_mappings

Note: do not specify whitespace around the "=" here.

AAddddrreessss mmaassqquueerraaddiinngg

Address masquerading is a method to hide hosts inside a domain behind their
mail gateway, and to make it appear as if the mail comes from the gateway
itself, instead of from individual machines.

NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP
clients only if the client matches the local_header_rewrite_clients parameter,
or if the remote_header_rewrite_domain configuration parameter specifies a non-
empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".

Address masquerading is disabled by default, and is implemented by the cleanup
(8) server. To enable, edit the masquerade_domains parameter in the main.cf
file and specify one or more domain names separated by whitespace or commas.
When Postfix tries to masquerade a domain, it processes the list from left to
right, and processing stops at the first match.

Example:

    /etc/postfix/main.cf:
        masquerade_domains = foo.example.com example.com

strips "any.thing.foo.example.com" to "foo.example.com", but strips
"any.thing.else.example.com" to "example.com".

A domain name prefixed with "!" means do not masquerade this domain or its
subdomains:

    /etc/postfix/main.cf:
        masquerade_domains = !foo.example.com example.com

does not change "any.thing.foo.example.com" and "foo.example.com", but strips
"any.thing.else.example.com" to "example.com".

The masquerade_exceptions configuration parameter specifies what user names
should not be subjected to address masquerading. Specify one or more user names
separated by whitespace or commas.

Example:

    /etc/postfix/main.cf:
        masquerade_exceptions = root

By default, Postfix makes no exceptions.

Subtle point: by default, address masquerading is applied only to message
headers and to envelope sender addresses, but not to envelope recipients. This
allows you to use address masquerading on a mail gateway machine, while still
being able to forward mail from outside to users on individual machines.

In order to subject envelope recipient addresses to masquerading, too, specify
(Postfix version 1.1 and later):

    /etc/postfix/main.cf:
        masquerade_classes = envelope_sender, envelope_recipient,
            header_sender, header_recipient

If you rewrite the envelope recipient like this, Postfix will no longer be able
to send mail to individual machines.

Address masquerading can be turned off selectively for mail received by smtpd
(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf
file. This feature is available in Postfix version 2.1 and later.

Example:

    /etc/postfix/master.cf:
        127.0.0.1:10026    inet  n      -      n      -      -     smtpd
            -o receive_override_options=no_address_mappings

Note: do not specify whitespace around the "=" here.

AAuuttoommaattiicc BBCCCC rreecciippiieennttss

After applying the canonical and masquerade mappings, the cleanup(8) daemon can
generate optional BCC (blind carbon-copy) recipients. Postfix provides three
mechanisms:

    always_bcc = address
        Deliver a copy of all mail to the specified address. In Postfix
        versions before 2.1, this feature is implemented by smtpd(8), qmqpd(8),
        or pickup(8).
    sender_bcc_maps = type:table
        Search the specified "type:table" lookup table with the envelope sender
        address for an automatic BCC address. This feature is available in
        Postfix 2.1 and later.
    recipient_bcc_maps = type:table
        Search the specified "type:table" lookup table with the envelope
        recipient address for an automatic BCC address. This feature is
        available in Postfix 2.1 and later.

Note: automatic BCC recipients are produced only for new mail. To avoid mailer
loops, automatic BCC recipients are not generated for mail that Postfix
forwards internally, nor for mail that Postfix generates itself.

Automatic BCC recipients (including always_bcc) can be turned off selectively
for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf
settings in the master.cf file. This feature is available in Postfix version
2.1 and later.

Example:

    /etc/postfix/master.cf:
        127.0.0.1:10026    inet  n      -      n      -      -     smtpd
            -o receive_override_options=no_address_mappings

Note: do not specify whitespace around the "=" here.

VViirrttuuaall aalliiaassiinngg

Before writing the recipients to the queue file, the cleanup(8) daemon uses the
optional virtual(5) alias tables to redirect mail for recipients. The mapping
affects only envelope recipient addresses; it has no effect on message headers
or envelope sender addresses. Virtual alias lookups are useful to redirect mail
for virtual alias domains to real user mailboxes, and to redirect mail for
domains that no longer exist. Virtual alias lookups can also be used to
transform " Firstname.Lastname " back into UNIX login names, although it seems
that local aliases may be a more appropriate vehicle. See the VIRTUAL_README
document for an overview of methods to host virtual domains with Postfix.

Virtual aliasing is disabled by default. To enable, edit the virtual_alias_maps
parameter in the main.cf file and specify one or more lookup tables, separated
by whitespace or commas.

Example:

    /etc/postfix/main.cf:
        virtual_alias_maps = hash:/etc/postfix/virtual

    /etc/postfix/virtual:
        Wietse.Venema        wietse

Addresses found in virtual alias maps are subjected to another iteration of
virtual aliasing, but are not subjected to canonical mapping, in order to avoid
loops.

For static mappings as shown above, lookup tables such as hash:, ldap:, mysql:
or pgsql: are sufficient. For dynamic mappings you can use regular expression
tables. This requires that you become intimately familiar with the ideas
expressed in regexp_table(5), pcre_table(5) and virtual(5).

Virtual aliasing can be turned off selectively for mail received by smtpd(8),
qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file.
This feature is available in Postfix version 2.1 and later.

Example:

    /etc/postfix/master.cf:
        127.0.0.1:10026    inet  n      -      n      -      -     smtpd
            -o receive_override_options=no_address_mappings

Note: do not specify whitespace around the "=" here.

At this point the message is ready to be stored into the Postfix incoming
queue.

AAddddrreessss rreewwrriittiinngg wwhheenn mmaaiill iiss ddeelliivveerreedd

The Postfix queue manager sorts mail according to its destination and gives it
to Postfix delivery agents such as local(8), smtp(8), or lmtp(8). Just like the
cleanup(8) server, the Postfix queue manager delegates the more complex address
manipulations to the trivial-rewrite(8) server.

Address manipulations at this stage are:

  * Resolve address to destination
  * Mail transport switch
  * Relocated users table

Each Postfix delivery agent tries to deliver the mail to its destination, while
encapsulating the sender, recipients, and message content according to the
rules of the SMTP, LMTP, etc. protocol. When mail cannot be delivered, it is
either returned to the sender or moved to the deferred queue and tried again
later.

Address manipulations when mail is delivered via the smtp(8) delivery agent:

  * Generic mapping for outgoing SMTP mail

Address manipulations when mail is delivered via the local(8) delivery agent:

  * Local alias database
  * Local per-user .forward files
  * Local catch-all address

The remainder of this document presents each address manipulation step in more
detail, with specific examples or with pointers to documentation with examples.

RReessoollvvee aaddddrreessss ttoo ddeessttiinnaattiioonn

The Postfix qmgr(8) queue manager selects new mail from the incoming queue or
old mail from the deferred queue, and asks the trivial-rewrite(8) address
rewriting and resolving daemon where it should be delivered.

As of version 2.0, Postfix distinguishes four major address classes. Each class
has its own list of domain names, and each class has its own default delivery
method, as shown in the table below. See the ADDRESS_CLASS_README document for
the fine details. Postfix versions before 2.0 only distinguish between local
delivery and everything else.

     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
    |DDeessttiinnaattiioonn ddoommaaiinn lliisstt          |DDeeffaauulltt ddeelliivveerryy mmeetthhoodd|AAvvaaiillaabbiilliittyy|
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ |
    |$mydestination, $inet_interfaces,|$local_transport       |Postfix 1.0 |
    |$proxy_interfaces                |                       |            |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ |
    |$virtual_mailbox_domains         |$virtual_transport     |Postfix 2.0 |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ |
    |$relay_domains                   |$relay_transport       |Postfix 2.0 |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ |
    |none                             |$default_transport     |Postfix 1.0 |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ |

MMaaiill ttrraannssppoorrtt sswwiittcchh

Once the trivial-rewrite(8) daemon has determined a default delivery method it
searches the optional transport(5) table for information that overrides the
message destination and/or delivery method. Typical use of the transport(5)
table is to send mail to a system that is not connected to the Internet, or to
use a special SMTP client configuration for destinations that have special
requirements. See, for example, the STANDARD_CONFIGURATION_README and
UUCP_README documents, and the examples in the transport(5) manual page.

Transport table lookups are disabled by default. To enable, edit the
transport_maps parameter in the main.cf file and specify one or more lookup
tables, separated by whitespace or commas.

Example:

    /etc/postfix/main.cf:
        transport_maps = hash:/etc/postfix/transport

RReellooccaatteedd uusseerrss ttaabbllee

Next, the trivial-rewrite(8) address rewriting and resolving daemon runs each
recipient through the relocated(5) database. This table provides information on
how to reach users that no longer have an account, or what to do with mail for
entire domains that no longer exist. When mail is sent to an address that is
listed in this table, the message is returned to the sender with an informative
message.

The relocated(5) database is searched after transport(5) table lookups, in
anticipation of transport(5) tables that can replace one recipient address by a
different one.

Lookups of relocated users are disabled by default. To enable, edit the
relocated_maps parameter in the main.cf file and specify one or more lookup
tables, separated by whitespace or commas.

Example:

    /etc/postfix/main.cf:
        relocated_maps = hash:/etc/postfix/relocated

    /etc/postfix/relocated:
        username@example.com      otheruser@elsewhere.tld

As of Postfix version 2, mail for a relocated user will be rejected by the SMTP
server with the reason "user has moved to otheruser@elsewhere.tld". Older
Postfix versions will receive the mail first, and then return it to the sender
as undeliverable, with the same reason.

GGeenneerriicc mmaappppiinngg ffoorr oouuttggooiinngg SSMMTTPP mmaaiill

Some hosts have no valid Internet domain name, and instead use a name such as
localdomain.local. This can be a problem when you want to send mail over the
Internet, because many mail servers reject mail addresses with invalid domain
names.

With the smtp_generic_maps parameter you can specify generic(5) lookup tables
that replace local mail addresses by valid Internet addresses when mail leaves
the machine via SMTP. The generic(5) mapping replaces envelope and header
addresses, and is non-recursive. It does not happen when you send mail between
addresses on the local machine.

This feature is available in Postfix version 2.2 and later.

Example:

    /etc/postfix/main.cf:
        smtp_generic_maps = hash:/etc/postfix/generic

    /etc/postfix/generic:
        his@localdomain.local               hisaccount@hisisp.example
        her@localdomain.local               heraccount@herisp.example
        @localdomain.local                  hisaccount+local@hisisp.example

When mail is sent to a remote host via SMTP, this replaces
his@localdomain.local by his ISP mail address, replaces her@localdomain.local
by her ISP mail address, and replaces other local addresses by his ISP account,
with an address extension of +local (this example assumes that the ISP supports
"+" style address extensions).

LLooccaall aalliiaass ddaattaabbaassee

When mail is to be delivered locally, the local(8) delivery agent runs each
local recipient name through the aliases(5) database. The mapping does not
affect addresses in message headers. Local aliases are typically used to
implement distribution lists, or to direct mail for standard aliases such as
postmaster to real people. The table can also be used to map
"Firstname.Lastname" addresses to login names.

Alias lookups are enabled by default. The default configuration depends on the
operating system environment, but it is typically one of the following:

    /etc/postfix/main.cf:
        alias_maps = hash:/etc/aliases
        alias_maps = dbm:/etc/aliases, nis:mail.aliases

The pathname of the alias database file is controlled with the alias_database
configuration parameter. The value is system dependent. Usually it is one of
the following:

    /etc/postfix/main.cf:
        alias_database = hash:/etc/aliases (4.4BSD, LINUX)
        alias_database = dbm:/etc/aliases (4.3BSD, SYSV<4)
        alias_database = dbm:/etc/mail/aliases (SYSV4)

An aliases(5) file can specify that mail should be delivered to a local file,
or to a command that receives the message in the standard input stream. For
security reasons, deliveries to command and file destinations are performed
with the rights of the alias database owner. A default userid, default_privs,
is used for deliveries to commands or files in "root"-owned aliases.

LLooccaall ppeerr--uusseerr ..ffoorrwwaarrdd ffiilleess

With delivery via the local(8) delivery agent, users can control their own mail
delivery by specifying destinations in a file called .forward in their home
directories. The syntax of these files is the same as with the local aliases(5)
file, except that the left-hand side of the alias (lookup key and colon) are
not present.

LLooccaall ccaattcchh--aallll aaddddrreessss

When the local(8) delivery agent finds that a message recipient does not exist,
the message is normally returned to the sender ("user unknown"). Sometimes it
is desirable to forward mail for non-existing recipients to another machine.
For this purpose you can specify an alternative destination with the
luser_relay configuration parameter.

Alternatively, mail for non-existent recipients can be delegated to an entirely
different message transport, as specified with the fallback_transport
configuration parameter. For details, see the local(8) delivery agent
documentation.

Note: if you use the luser_relay feature in order to receive mail for non-UNIX
accounts, then you must specify:

    /etc/postfix/main.cf:
        local_recipient_maps =

(i.e. empty) in the main.cf file, otherwise the Postfix SMTP server will reject
mail for non-UNIX accounts with "User unknown in local recipient table". See
the LOCAL_RECIPIENT_README file for more information on this.

luser_relay can specify one address. It is subjected to "$name" expansions.
Examples:

    $user@other.host
        The bare username, without address extension, is prepended to
        "@other.host". For example, mail for "username+foo" is sent to
        "username@other.host".

    $local@other.host
        The entire original recipient localpart, including address extension,
        is prepended to "@other.host". For example, mail for "username+foo" is
        sent to "username+foo@other.host".

    sysadmin+$user
        The bare username, without address extension, is appended to
        "sysadmin". For example, mail for "username+foo" is sent to
        "sysadmin+username".

    sysadmin+$local
        The entire original recipient localpart, including address extension,
        is appended to "sysadmin". For example, mail for "username+foo" is sent
        to "sysadmin+username+foo".

DDeebbuuggggiinngg yyoouurr aaddddrreessss mmaanniippuullaattiioonnss

Postfix version 2.1 and later can produce mail delivery reports for debugging
purposes. These reports not only show sender/recipient addresses after address
rewriting and alias expansion or forwarding, they also show information about
delivery to mailbox, delivery to non-Postfix command, responses from remote
SMTP servers, and so on.

Postfix can produce two types of mail delivery reports for debugging:

  * What-if: report what would happen, but do not actually deliver mail. This
    mode of operation is requested with:

    $ //uussrr//ssbbiinn//sseennddmmaaiill --bbvv aaddddrreessss......
    Mail Delivery Status Report will be mailed to <your login name>.

  * What happened: deliver mail and report successes and/or failures, including
    replies from remote SMTP servers. This mode of operation is requested with:

    $ //uussrr//ssbbiinn//sseennddmmaaiill --vv aaddddrreessss......
    Mail Delivery Status Report will be mailed to <your login name>.

These reports contain information that is generated by Postfix delivery agents.
Since these run as daemon processes and do not interact with users directly,
the result is sent as mail to the sender of the test message. The format of
these reports is practically identical to that of ordinary non-delivery
notifications.

As an example, below is the delivery report that is produced with the command
"sendmail -bv postfix-users@postfix.org". The first part of the report contains
human-readable text. In this case, mail would be delivered via mail.cloud9.net,
and the SMTP server replies with "250 Ok". Other reports may show delivery to
mailbox, or delivery to non-Postfix command.

    Content-Description: Notification
    Content-Type: text/plain

    This is the mail system at host spike.porcupine.org.

    Enclosed is the mail delivery report that you requested.

                            The mail system

    <postfix-users@postfix.org>: delivery via mail.cloud9.net[168.100.1.4]: 250
    2.1.5 Ok

The second part of the report is in machine-readable form, and includes the
following information:

  * The envelope sender address (wietse@porcupine.org).
  * The envelope recipient address (postfix-users@postfix.org). If the
    recipient address was changed by Postfix then Postfix also includes the
    original recipient address.
  * The delivery status.

Some details depend on Postfix version. The example below is for Postfix
version 2.3 and later.

    Content-Description: Delivery report
    Content-Type: message/delivery-status

    Reporting-MTA: dns; spike.porcupine.org
    X-Postfix-Queue-ID: 84863BC0E5
    X-Postfix-Sender: rfc822; wietse@porcupine.org
    Arrival-Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST)

    Final-Recipient: rfc822; postfix-users@postfix.org
    Action: deliverable
    Status: 2.1.5
    Remote-MTA: dns; mail.cloud9.net
    Diagnostic-Code: smtp; 250 2.1.5 Ok

The third part of the report contains the message that Postfix would have
delivered, including From: and To: message headers, so that you can see any
effects of address rewriting on those. Mail submitted with "sendmail -bv" has
no body content so none is shown in the example below.

    Content-Description: Message
    Content-Type: message/rfc822

    Received: by spike.porcupine.org (Postfix, from userid 1001)
            id 84863BC0E5; Sun, 26 Nov 2006 17:01:01 -0500 (EST)
    Subject: probe
    To: postfix-users@postfix.org
    Message-Id: <20061126220101.84863BC0E5@spike.porcupine.org>
    Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST)
    From: wietse@porcupine.org (Wietse Venema)