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
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Postfix Address Rewriting </title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
</head>
<body>
<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix
Address Rewriting </h1>
<hr>
<h2> <a name="purpose"> Postfix address rewriting purpose </a> </h2>
<p> 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: </p>
<ul>
<li> <p> 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".
</p>
<li> <p> 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. </p>
<li> <p> 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.
</p>
<li> <p> Replace an address by multiple addresses. For example,
replace the address of an alias by the addresses listed under that
alias. </p>
<li> <p> 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". </p>
</ul>
<p> 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. </p>
<p> Topics covered in this document: </p>
<ul>
<li> <a href="#william"> To rewrite message headers or not, or to label
as invalid </a>
<li> <a href="#overview"> Postfix address rewriting overview </a>
<li> <a href="#receiving"> Address rewriting when mail is received</a>
<ul>
<li> <a href="#standard"> Rewrite addresses to standard form</a>
<li> <a href="#canonical"> Canonical address mapping </a>
<li> <a href="#masquerade"> Address masquerading </a>
<li> <a href="#auto_bcc"> Automatic BCC recipients</a>
<li> <a href="#virtual"> Virtual aliasing </a>
</ul>
<li> <a href="#delivering"> Address rewriting when mail is delivered</a>
<ul>
<li> <a href="#resolve"> Resolve address to (transport, next-hop destination) </a>
<li> <a href="#relocated"> Relocated users table </a>
</ul>
<li> <a href="#remote"> Address rewriting with remote delivery </a>
<ul>
<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a>
</ul>
<li> <a href="#local"> Address rewriting with local delivery </a>
<ul>
<li> <a href="#aliases"> Local alias database </a>
<li> <a href="#forward"> Local per-user .forward files </a>
<li> <a href="#luser_relay"> Local catch-all address </a>
</ul>
<li> <a href="#debugging"> Debugging your address manipulations </a>
</ul>
<h2> <a name="william"> To rewrite message headers or not, or to label
as invalid </a> </h2>
<p> 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: </p>
<ul>
<li> Message header address rewriting is frowned upon by mail standards,
<li> Appending Postfix's own domain produces incorrect results with
some incomplete addresses,
<li> Appending Postfix's own domain sometimes creates the appearance
that spam is sent by local users.
</ul>
<p> 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: </p>
<ul>
<li> 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).
<li> Postfix never rewrites message header addresses from remote
SMTP clients when the remote_header_rewrite_domain parameter value
is empty (the default setting).
<li> 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.
</ul>
<h2> <a name="overview"> Postfix address rewriting overview </a> </h2>
<p> 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. </p>
<blockquote>
<table>
<tr>
<td colspan="2"> </td>
<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(std
form) </td>
<td colspan="5"> </td>
<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(resolve)
</td>
</tr>
<tr>
<td colspan="2"> </td>
<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>
<td colspan="5"> </td>
<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>
<td colspan="2"> </td>
</tr>
<tr>
<td bgcolor="#f0f0ff" align="center" valign="middle"> smtpd(8)
</td>
<td rowspan="3" align="center" valign="middle"> <tt> >- </tt>
</td>
<td rowspan="3" bgcolor="#f0f0ff" align="center"> cleanup(8) </td>
<td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
</td>
<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#incoming_queue"> incoming </a> </td>
<td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
</td>
<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#active_queue"> active </a> </td>
<td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
</td>
<td rowspan="3" bgcolor="#f0f0ff" align="center"> qmgr(8) </td>
<td rowspan="3" align="center" valign="middle"> <tt> -< </tt>
</td>
<td bgcolor="#f0f0ff" align="center" valign="middle">
smtp(8) </td>
</tr>
<tr>
<td bgcolor="#f0f0ff" align="center" valign="middle">
qmqpd(8) </td>
<td bgcolor="#f0f0ff" align="center" valign="middle"> lmtp(8) </td>
</tr>
<tr>
<td bgcolor="#f0f0ff" align="center" valign="middle"> pickup(8)
</td>
<td bgcolor="#f0f0ff" align="center" valign="middle"> local(8)
</td>
</tr>
<tr>
<td colspan="2"> </td>
<td align="center"> ^<br> <tt> | </tt> </td>
<td colspan="3"> </td>
<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>
<td colspan="4"> </td>
</tr>
<tr>
<td colspan="2"> </td>
<td align="center"> bounces<br> forwarding<br> notices</td>
<td colspan="3"> </td>
<td bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#deferred_queue"> deferred </a>
<td colspan="2"> </td>
</table>
</blockquote>
<p> The table below summarizes all Postfix address manipulations.
If you're reading this document for the first time, skip forward
to "<a href="ADDRESS_REWRITING_README.html#receiving">Address
rewriting when mail is received</a>". Once you've finished reading
the remainder of this document, the table will help you to quickly
find what you need. </p>
<blockquote>
<table border="1">
<tr> <th nowrap> Address manipulation </th> <th nowrap> Scope </th>
<th> Daemon </th> <th nowrap> Turn-on controls </th> <th nowrap>
Turn-off controls </th> </tr>
<tr> <td> <a href="#standard"> Rewrite addresses to standard form</a>
</td> <td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td>
<td> append_at_myorigin, append_dot_mydomain, swap_bangpath,
allow_percent_hack </td> <td> local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>
<tr> <td> <a href="#canonical"> Canonical address mapping </a> </td>
<td nowrap> all mail </td> <td> cleanup(8) </td> <td> canonical_maps
</td> <td> receive_override_options, local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>
<tr> <td> <a href="#masquerade"> Address masquerading </a> </td> <td
nowrap> all mail </td> <td> cleanup(8) </td> <td> masquerade_domains
</td> <td> receive_override_options, local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>
<tr> <td> <a href="#auto_bcc"> Automatic BCC recipients </a> </td>
<td nowrap> new mail </td> <td> cleanup(8) </td> <td> always_bcc,
sender_bcc_maps, recipient_bcc_maps </td> <td> receive_override_options
</td> </tr>
<tr> <td> <a href="#virtual"> Virtual aliasing </a> </td> <td
nowrap> all mail </td> <td> cleanup(8) </td> <td> virtual_alias_maps
</td> <td> receive_override_options </td> </tr>
<tr> <td> <a href="#resolve"> Resolve address to (transport, next-hop
destination) </a> </td> <td nowrap> all mail </td> <td>
trivial-<br>rewrite(8) </td> <td> local_transport, virtual_transport,
relay_transport, default_transport, relayhost,
sender_dependent_relayhost_maps, sender_dependent_default_transport_maps
</td> <td> content_filter </td> </tr>
<tr> <td> <a href="#relocated"> Relocated users table</a> </td>
<td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> <td>
relocated_maps </td> <td> none </td> </tr>
<tr> <td> <a href="#generic"> Generic mapping table </a> </td> <td>
outgoing SMTP mail </td> <td> smtp(8) </td> <td> smtp_generic_maps
</td> <td> none </td> </tr>
<tr> <td> <a href="#aliases"> Local alias database</a> </td> <td>
local mail only </td> <td> local(8) </td> <td> alias_maps </td> <td> none
</td> </tr>
<tr> <td> <a href="#forward"> Local per-user .forward files</a>
</td> <td> local mail only </td> <td> local(8) </td> <td> forward_path
</td> <td> none </td> </tr>
<tr> <td> <a href="#luser_relay"> Local catch-all address</a> </td>
<td> local mail only </td> <td> local(8) </td> <td> luser_relay </td> <td>
none </td> </tr>
</table>
</blockquote>
<h2> <a name="receiving"> Address rewriting when mail is received</a>
</h2>
<p> 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. </p>
<p> 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.
</p>
<p> Address manipulations at this stage are: </p>
<ul>
<li> <a href="#standard"> Rewrite addresses to standard form</a>
<li> <a href="#canonical"> Canonical address mapping</a>
<li> <a href="#masquerade"> Address masquerading</a>
<li> <a href="#auto_bcc"> Automatic BCC recipients</a>
<li> <a href="#virtual"> Virtual aliasing </a>
</ul>
<h3> <a name="standard"> Rewrite addresses to standard form</a> </h3>
<p> 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.
</p>
<p> The Postfix trivial-rewrite(8) daemon implements the following
hard-coded address manipulations: </p>
<blockquote>
<dl>
<dt>Rewrite "@hosta,@hostb:user@site" to "user@site"</dt>
<dd> <p> 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. </p>
<p> 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". </p> </dd>
<dt>Rewrite "site!user" to "user@site" </dt>
<dd> <p> 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. </p>
<p> 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". </p> </dd>
<dt>Rewrite "user%domain" to "user@domain"</dt>
<dd> <p> 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". </p>
<p> 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". </p> </dd>
<dt>
Rewrite "user" to "user@$myorigin" </dt>
<dd> <p> 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". </p>
<p> 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". </p>
<p> 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 <a href="#virtual">virtual
alias</a> table that redirects "user@$myorigin" to
"user@$myhostname". See also the "delivering some
users locally" section in the STANDARD_CONFIGURATION_README
document. </p> </dd>
<dt>
Rewrite "user@host" to "user@host.$mydomain" </dt>
<dd> <p> This feature is controlled by the boolean append_dot_mydomain
parameter (default: Postfix ≥ 3.0: no, Postfix < 3.0: yes). The purpose
is to get consistent treatment of different forms of the same hostname. </p>
<p> 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". </p>
<p> 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. </p> </dd>
<dt>Rewrite "user@site." to "user@site" (without the trailing dot).</dt>
<dd> <p> A single trailing dot is silently removed. However, an
address that ends in multiple dots will be rejected as an invalid
address. </p>
<p> 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". </p> </dd>
</dl>
</blockquote>
<h3> <a name="canonical"> Canonical address mapping </a> </h3>
<p> 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. </p>
<p> 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". </p>
<p> 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. </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
canonical_maps = hash:/etc/postfix/canonical
/etc/postfix/canonical:
wietse Wietse.Venema
</pre>
</blockquote>
<p> 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). </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
sender_canonical_maps = hash:/etc/postfix/sender_canonical
recipient_canonical_maps = hash:/etc/postfix/recipient_canonical
</pre>
</blockquote>
<p> 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. </p>
<p> 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.
</p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/master.cf:
127.0.0.1:10026 inet n - n - - smtpd
-o receive_override_options=no_address_mappings
</pre>
</blockquote>
<p> Note: do not specify whitespace around the "=" here. </p>
<h3> <a name="masquerade"> Address masquerading </a> </h3>
<p> 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.
</p>
<p> 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". </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
masquerade_domains = foo.example.com example.com
</pre>
</blockquote>
<p> strips "any.thing.foo.example.com" to "foo.example.com", but
strips "any.thing.else.example.com" to "example.com". </p>
<p> A domain name prefixed with "<tt>!</tt>" means do not masquerade
this domain or its subdomains: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
masquerade_domains = !foo.example.com example.com
</pre>
</blockquote>
<p> does not change "any.thing.foo.example.com" and "foo.example.com",
but strips "any.thing.else.example.com" to "example.com". </p>
<p> 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.
</p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
masquerade_exceptions = root
</pre>
</blockquote>
<p> By default, Postfix makes no exceptions. </p>
<p> 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. </p>
<p> In order to subject envelope recipient addresses to masquerading,
too, specify (Postfix version 1.1 and later):</p>
<blockquote>
<pre>
/etc/postfix/main.cf:
masquerade_classes = envelope_sender, envelope_recipient,
header_sender, header_recipient
</pre>
</blockquote>
<p> If you rewrite the envelope recipient like this, Postfix will
no longer be able to send mail to individual machines. </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/master.cf:
127.0.0.1:10026 inet n - n - - smtpd
-o receive_override_options=no_address_mappings
</pre>
</blockquote>
<p> Note: do not specify whitespace around the "=" here. </p>
<h3> <a name="auto_bcc"> Automatic BCC recipients</a> </h3>
<p> After applying the canonical and masquerade mappings, the
cleanup(8) daemon can generate optional BCC (blind carbon-copy)
recipients. Postfix provides three mechanisms: </p>
<blockquote>
<dl>
<dt> always_bcc = address </dt> <dd> 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). </dd>
<dt> sender_bcc_maps = type:table </dt> <dd> 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. </dd>
<dt> recipient_bcc_maps = type:table </dt> <dd> 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. </dd>
</dl>
</blockquote>
<p> 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. </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/master.cf:
127.0.0.1:10026 inet n - n - - smtpd
-o receive_override_options=no_address_mappings
</pre>
</blockquote>
<p> Note: do not specify whitespace around the "=" here. </p>
<h3> <a name="virtual"> Virtual aliasing </a> </h3>
<p> 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 <a href="#aliases">aliases</a>
may be a more appropriate vehicle. See the VIRTUAL_README document
for an overview of methods to host virtual domains with Postfix.
</p>
<p> Note: virtual aliasing (virtual_alias_maps) applies to all
recipients: local(8), virtual, and remote. <!-- wrap filler -->
This is unlike local aliasing (alias_maps) which applies only to
local(8) recipients. </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
virtual_alias_maps = hash:/etc/postfix/virtual
/etc/postfix/virtual:
Wietse.Venema wietse
</pre>
</blockquote>
<p> 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. </p>
<p> 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). </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/master.cf:
127.0.0.1:10026 inet n - n - - smtpd
-o receive_override_options=no_address_mappings
</pre>
</blockquote>
<p> Note: do not specify whitespace around the "=" here. </p>
<p> At this point the message is ready to be stored into the
Postfix incoming queue. </p>
<h2> <a name="delivering"> Address rewriting when mail is delivered</a> </h2>
<p> 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. </p>
<p> Address manipulations at this stage are: </p>
<ul>
<li> <a href="#resolve"> Resolve address to (transport, next-hop
destination) </a>
<li> <a href="#relocated"> Relocated users table</a>
</ul>
<p> 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. </p>
<p> <a name="remote">Address</a> manipulations when mail is delivered
via the smtp(8) delivery agent: </p>
<ul>
<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a>
</ul>
<p> <a name="local">Address</a> manipulations when mail is delivered
via the local(8) delivery agent: </p>
<ul>
<li> <a href="#aliases"> Local alias database</a>
<li> <a href="#forward"> Local per-user .forward files</a>
<li> <a href="#luser_relay"> Local catch-all address</a>
</ul>
<p> The remainder of this document presents each address manipulation
step in more detail, with specific examples or with pointers to
documentation with examples. </p>
<h3> <a name="resolve"> Resolve address to (transport, next-hop
destination) </a> </h3>
<p> The Postfix qmgr(8) queue manager selects new mail from the
incoming queue or old mail from the deferred queue. First it
looks for overrides: </p>
<ul>
<li> <p> The REDIRECT action in access(5), header_checks(5) or
body_checks(5) overrides all recipients of the message, and overrides
a content_filter setting, and FILTER action in access(5),
header_checks(5) or body_checks(5). The REDIRECT action was implemented
as a short-cut to retaliate for abuse. </p>
<li> <p> A content_filter setting and FILTER action in access(5),
header_checks(5) or body_checks(5) provide their own (transport,
next-hop destination) information. This bypasses all the steps that
are described in the remainder of this section. </p>
</ul>
<p> When there is no content filter override, the qmgr(8) queue
manager asks the trivial-rewrite(8) address rewriting and resolving
daemon for each recipient how to deliver it (which message delivery
transport) and where to deliver it (what next-hop destination). </p>
<p> As of version 2.0, Postfix distinguishes four major domain
classes. Each class has its own list of recipient domain names, and
each class has its own 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. </p>
<p> Note that the table does not match recipients against
virtual_alias_domains. The reason is that all valid recipients in
a virtual alias domain must be aliased to an address in a different
domain. All other recipients in a virtual alias domain are by
definition undeliverable, and do not need to be considered here.
</p>
<blockquote>
<table border="1">
<tr> <th align="left">Domain class</th> <th align="left">Recipient
domain match </th> <th> Delivery method </th> <th>Availability </th>
</tr>
<tr><td>Local</td> <td>mydestination, inet_interfaces, proxy_interfaces
</td> <td>local_transport </td> <td>Postfix 1.0</td></tr>
<tr><td>Virtual mailbox</td> <td>virtual_mailbox_domains </td>
<td>virtual_transport </td> <td>Postfix 2.0</td> </tr>
<tr><td>Relay</td> <td>relay_domains </td> <td>relay_transport
</td> <td>Postfix 2.0</td> </tr>
<tr><td>Default</td><td> none </td> <td>default_transport </td>
<td>Postfix 1.0</td> </tr>
</table>
</blockquote>
<p> The delivery methods in the above table may include a next-hop
destination in addition to a delivery transport. This may override
the next-hop destination that is by default taken from the recipient
domain. </p>
<p> Over time, features have been added to override the above
transport and/or next-hop destination information. The following
table lists where a transport or next-hop destination may be taken
from, depending on the recipient domain class. </p>
<blockquote>
<table border="1">
<tr> <th>Domain class</th> <th>Transport sources (in order of
descending precedence)</th> <th> Next hop sources (in order of
descending precedence)</th> </tr>
<tr> <td> Local </td> <td> transport_maps, local_transport</td>
<td> transport_maps, local_transport, recipient domain</td> </tr>
<tr> <td> Virtual mailbox </td> <td> transport_maps,
virtual_transport</td> <td> transport_maps, virtual_transport,
recipient domain</td> </tr>
<tr> <td> Relay </td> <td> transport_maps, relay_transport</td>
<td> transport_maps, relay_transport, sender_dependent_relayhost_maps,
relayhost, recipient domain</td> </tr>
<tr> <td> Default </td> <td> transport_maps,
sender_dependent_default_transport_maps, default_transport</td>
<td> transport_maps, sender_dependent_default_transport_maps,
default_transport, sender_dependent_relayhost_maps, relayhost,
recipient domain</td> </tr>
</table>
</blockquote>
<h3> <a name="relocated"> Relocated users table </a> </h3>
<p> 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. </p>
<p> 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. </p>
<p> 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. </p>
<p> Example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
relocated_maps = hash:/etc/postfix/relocated
/etc/postfix/relocated:
username@example.com otheruser@elsewhere.tld
</pre>
</blockquote>
<p> 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. </p>
<h3> <a name="generic"> Generic mapping for outgoing SMTP mail </a> </h3>
<p> Some hosts have no valid Internet domain name, and instead use
a name such as <i>localdomain.local</i>. 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. </p>
<p> 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. </p>
<p> This feature is available in Postfix version 2.2 and later.</p>
<p> Example: </p>
<blockquote>
<pre>
/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
</pre>
</blockquote>
<p> When mail is sent to a remote host via SMTP, this replaces
<i>his@localdomain.local</i> by his ISP mail address, replaces
<i>her@localdomain.local</i> by her ISP mail address, and replaces
other local addresses by his ISP account, with an address extension
of +<i>local</i> (this example assumes that the ISP supports "+"
style address extensions). </p>
<h3> <a name="aliases"> Local alias database </a> </h3>
<p> 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. </p>
<p> Note: local aliasing (alias_maps) applies only to local(8)
recipients. This is unlike virtual aliasing (virtual_alias_maps)
which applies to all recipients: local(8), virtual, and remote.
</p>
<p> Alias lookups are enabled by default. The default configuration
depends on the operating system environment, but it is typically
one of the following: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
alias_maps = hash:/etc/aliases
alias_maps = dbm:/etc/aliases, nis:mail.aliases
</pre>
</blockquote>
<p> 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: </p>
<blockquote>
<pre>
/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)
</pre>
</blockquote>
<p> 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. </p>
<h3> <a name="forward"> Local per-user .forward files </a> </h3>
<p> 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. </p>
<h3> <a name="luser_relay"> Local catch-all address </a> </h3>
<p> 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. </p>
<p> 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. </p>
<p> Note: if you use the luser_relay feature in order to receive
mail for non-UNIX accounts, then you must specify: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
local_recipient_maps =
</pre>
</blockquote>
<p> (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.
</p>
<p> luser_relay can specify one address. It is subjected to "$name"
expansions. Examples: </p>
<blockquote>
<dl>
<dt>$user@other.host </dt>
<dd> <p> The bare username, without address extension, is prepended
to "@other.host". For example, mail for "username+foo" is sent to
"username@other.host". </p> </dd>
<dt>$local@other.host </dt>
<dd> <p> 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". </p> </dd>
<dt>sysadmin+$user </dt>
<dd> <p> The bare username, without address extension, is appended
to "sysadmin". For example, mail for "username+foo" is sent to
"sysadmin+username". </p> </dd>
<dt>sysadmin+$local </dt>
<dd> <p> The entire original recipient localpart, including address
extension, is appended to "sysadmin". For example, mail for
"username+foo" is sent to "sysadmin+username+foo". </p> </dd>
</dl>
</blockquote>
<h2> <a name="debugging"> Debugging your address manipulations </a> </h2>
<p> 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. </p>
<p> Postfix can produce two types of mail delivery reports for
debugging: </p>
<ul>
<li> <p> What-if: report what would happen, but do not actually
deliver mail. This mode of operation is requested with: </p>
<pre>
$ <b>/usr/sbin/sendmail -bv address...</b>
Mail Delivery Status Report will be mailed to <your login name>.
</pre>
<li> <p> What happened: deliver mail and report successes and/or
failures, including replies from remote SMTP servers. This mode
of operation is requested with: </p>
<pre>
$ <b>/usr/sbin/sendmail -v address...</b>
Mail Delivery Status Report will be mailed to <your login name>.
</pre>
</ul>
<p> 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. </p>
<p> 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. </p>
<blockquote>
<pre>
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
</pre>
</blockquote>
<p> The second part of the report is in machine-readable form, and
includes the following information: </p>
<ul>
<li> The envelope sender address (wietse@porcupine.org).
<li> The envelope recipient address (postfix-users@postfix.org).
If the recipient address was changed by Postfix then Postfix also
includes the original recipient address.
<li> The delivery status.
</ul>
<p> Some details depend on Postfix version. The example below is
for Postfix version 2.3 and later. </p>
<blockquote>
<pre>
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
</pre>
</blockquote>
<p> 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. </p>
<blockquote>
<pre>
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)
</pre>
</blockquote>
</body>
</html>
|
