17
17
<b>postmap -q - /etc/postfix/canonical</b> <<i>inputfile</i>
20
The optional <a href="canonical.5.html"><b>canonical</b>(5)</a> table specifies an address map-
21
ping for local and non-local addresses. The mapping is
22
used by the <a href="cleanup.8.html"><b>cleanup</b>(8)</a> daemon, before mail is stored into
23
the queue. The address mapping is recursive.
25
Normally, the <a href="canonical.5.html"><b>canonical</b>(5)</a> table is specified as a text
26
file that serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The
27
result, an indexed file in <b>dbm</b> or <b>db</b> format, is used for
28
fast searching by the mail system. Execute the command
29
"<b>postmap /etc/postfix/canonical</b>" to rebuild an indexed
30
file after changing the corresponding text file.
32
When the table is provided via other means such as NIS,
33
LDAP or SQL, the same lookups are done as for ordinary
36
Alternatively, the table can be provided as a regular-
37
expression map where patterns are given as regular expres-
38
sions, or lookups can be directed to TCP-based server. In
39
those cases, the lookups are done in a slightly different
40
way as described below under "REGULAR EXPRESSION TABLES"
41
or "TCP-BASED TABLES".
43
By default the <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping affects both message
44
header addresses (i.e. addresses that appear inside mes-
45
sages) and message envelope addresses (for example, the
46
addresses that are used in SMTP protocol commands). This
47
is controlled with the <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b> parameter.
49
NOTE: Postfix versions 2.2 and later rewrite message head-
50
ers from remote SMTP clients only if the client matches
51
the <a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> parameter, or if the
52
<a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> configuration parameter spec-
53
ifies a non-empty value. To get the behavior before Post-
54
fix 2.2, specify "<a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> =
57
Typically, one would use the <a href="canonical.5.html"><b>canonical</b>(5)</a> table to replace
58
login names by <i>Firstname.Lastname</i>, or to clean up
59
addresses produced by legacy mail systems.
61
The <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping is not to be confused with <i>vir-</i>
62
<i>tual alias</i> support or with local aliasing. To change the
63
destination but not the headers, use the <a href="virtual.5.html"><b>virtual</b>(5)</a> or
64
<a href="aliases.5.html"><b>aliases</b>(5)</a> map instead.
20
The optional <a href="canonical.5.html"><b>canonical</b>(5)</a> table specifies an address mapping for local
21
and non-local addresses. The mapping is used by the <a href="cleanup.8.html"><b>cleanup</b>(8)</a> daemon,
22
before mail is stored into the queue. The address mapping is recur-
25
Normally, the <a href="canonical.5.html"><b>canonical</b>(5)</a> table is specified as a text file that
26
serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The result, an indexed file
27
in <b>dbm</b> or <b>db</b> format, is used for fast searching by the mail system.
28
Execute the command "<b>postmap /etc/postfix/canonical</b>" to rebuild an
29
indexed file after changing the corresponding text file.
31
When the table is provided via other means such as NIS, LDAP or SQL,
32
the same lookups are done as for ordinary indexed files.
34
Alternatively, the table can be provided as a regular-expression map
35
where patterns are given as regular expressions, or lookups can be
36
directed to TCP-based server. In those cases, the lookups are done in a
37
slightly different way as described below under "REGULAR EXPRESSION
38
TABLES" or "TCP-BASED TABLES".
40
By default the <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping affects both message header
41
addresses (i.e. addresses that appear inside messages) and message
42
envelope addresses (for example, the addresses that are used in SMTP
43
protocol commands). This is controlled with the <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b>
46
NOTE: Postfix versions 2.2 and later rewrite message headers from
47
remote SMTP clients only if the client matches the <a href="postconf.5.html#local_header_rewrite_clients">local_header_re</a>-
48
<a href="postconf.5.html#local_header_rewrite_clients">write_clients</a> parameter, or if the <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> config-
49
uration parameter specifies a non-empty value. To get the behavior
50
before Postfix 2.2, specify "<a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> =
51
<a href="DATABASE_README.html#types">static</a>:all".
53
Typically, one would use the <a href="canonical.5.html"><b>canonical</b>(5)</a> table to replace login names
54
by <i>Firstname.Lastname</i>, or to clean up addresses produced by legacy mail
57
The <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping is not to be confused with <i>virtual alias</i> sup-
58
port or with local aliasing. To change the destination but not the
59
headers, use the <a href="virtual.5.html"><b>virtual</b>(5)</a> or <a href="aliases.5.html"><b>aliases</b>(5)</a> map instead.
66
61
<b>CASE FOLDING</b>
67
The search string is folded to lowercase before database
68
lookup. As of Postfix 2.3, the search string is not case
69
folded with database types such as <a href="regexp_table.5.html">regexp</a>: or <a href="pcre_table.5.html">pcre</a>: whose
70
lookup fields can match both upper and lower case.
62
The search string is folded to lowercase before database lookup. As of
63
Postfix 2.3, the search string is not case folded with database types
64
such as <a href="regexp_table.5.html">regexp</a>: or <a href="pcre_table.5.html">pcre</a>: whose lookup fields can match both upper and
72
67
<b>TABLE FORMAT</b>
73
68
The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows:
76
When <i>pattern</i> matches a mail address, replace it by
77
the corresponding <i>result</i>.
70
<i>pattern address</i>
71
When <i>pattern</i> matches a mail address, replace it by the corre-
72
sponding <i>address</i>.
79
74
blank lines and comments
80
Empty lines and whitespace-only lines are ignored,
81
as are lines whose first non-whitespace character
75
Empty lines and whitespace-only lines are ignored, as are lines
76
whose first non-whitespace character is a `#'.
85
A logical line starts with non-whitespace text. A
86
line that starts with whitespace continues a logi-
79
A logical line starts with non-whitespace text. A line that
80
starts with whitespace continues a logical line.
89
82
<b>TABLE SEARCH ORDER</b>
90
With lookups from indexed files such as DB or DBM, or from
91
networked tables such as NIS, LDAP or SQL, patterns are
92
tried in the order as listed below:
83
With lookups from indexed files such as DB or DBM, or from networked
84
tables such as NIS, LDAP or SQL, patterns are tried in the order as
94
87
<i>user</i>@<i>domain address</i>
95
Replace <i>user</i>@<i>domain</i> by <i>address</i>. This form has the
88
Replace <i>user</i>@<i>domain</i> by <i>address</i>. This form has the highest prece-
98
This is useful to clean up addresses produced by
99
legacy mail systems. It can also be used to pro-
100
duce <i>Firstname.Lastname</i> style addresses, but see
101
below for a simpler solution.
91
This is useful to clean up addresses produced by legacy mail
92
systems. It can also be used to produce <i>Firstname.Lastname</i>
93
style addresses, but see below for a simpler solution.
103
95
<i>user address</i>
104
Replace <i>user</i>@<i>site</i> by <i>address</i> when <i>site</i> is equal to
105
$<b><a href="postconf.5.html#myorigin">myorigin</a></b>, when <i>site</i> is listed in $<b><a href="postconf.5.html#mydestination">mydestination</a></b>,
106
or when it is listed in $<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b> or
107
$<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>.
96
Replace <i>user</i>@<i>site</i> by <i>address</i> when <i>site</i> is equal to $<b><a href="postconf.5.html#myorigin">myorigin</a></b>,
97
when <i>site</i> is listed in $<b><a href="postconf.5.html#mydestination">mydestination</a></b>, or when it is listed in
98
$<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b> or $<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>.
109
This form is useful for replacing login names by
110
<i>Firstname.Lastname</i>.
100
This form is useful for replacing login names by <i>Firstname.Last-</i>
112
103
@<i>domain address</i>
113
Replace other addresses in <i>domain</i> by <i>address</i>. This
114
form has the lowest precedence.
104
Replace other addresses in <i>domain</i> by <i>address</i>. This form has the
116
Note: @<i>domain</i> is a wild-card. When this form is
117
applied to recipient addresses, the Postfix SMTP
118
server accepts mail for any recipient in <i>domain</i>,
119
regardless of whether that recipient exists. This
120
may turn your mail system into a backscatter
121
source: Postfix first accepts mail for non-existent
122
recipients and then tries to return that mail as
123
"undeliverable" to the often forged sender address.
107
Note: @<i>domain</i> is a wild-card. When this form is applied to
108
recipient addresses, the Postfix SMTP server accepts mail for
109
any recipient in <i>domain</i>, regardless of whether that recipient
110
exists. This may turn your mail system into a backscatter
111
source: Postfix first accepts mail for non-existent recipients
112
and then tries to return that mail as "undeliverable" to the
113
often forged sender address.
125
115
<b>RESULT ADDRESS REWRITING</b>
126
116
The lookup result is subject to address rewriting:
128
<b>o</b> When the result has the form @<i>otherdomain</i>, the
129
result becomes the same <i>user</i> in <i>otherdomain</i>.
131
<b>o</b> When "<b><a href="postconf.5.html#append_at_myorigin">append_at_myorigin</a>=yes</b>", append "<b>@$<a href="postconf.5.html#myorigin">myorigin</a></b>"
132
to addresses without "@domain".
134
<b>o</b> When "<b><a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b>", append "<b>.$<a href="postconf.5.html#mydomain">mydomain</a></b>"
135
to addresses without ".domain".
118
<b>o</b> When the result has the form @<i>otherdomain</i>, the result becomes
119
the same <i>user</i> in <i>otherdomain</i>.
121
<b>o</b> When "<b><a href="postconf.5.html#append_at_myorigin">append_at_myorigin</a>=yes</b>", append "<b>@$<a href="postconf.5.html#myorigin">myorigin</a></b>" to addresses
124
<b>o</b> When "<b><a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b>", append "<b>.$<a href="postconf.5.html#mydomain">mydomain</a></b>" to addresses
137
127
<b>ADDRESS EXTENSION</b>
138
When a mail address localpart contains the optional recip-
139
ient delimiter (e.g., <i>user+foo</i>@<i>domain</i>), the lookup order
140
becomes: <i>user+foo</i>@<i>domain</i>, <i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and
128
When a mail address localpart contains the optional recipient delimiter
129
(e.g., <i>user+foo</i>@<i>domain</i>), the lookup order becomes: <i>user+foo</i>@<i>domain</i>,
130
<i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and @<i>domain</i>.
143
The <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> parameter controls
144
whether an unmatched address extension (<i>+foo</i>) is propa-
145
gated to the result of table lookup.
132
The <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> parameter controls whether an
133
unmatched address extension (<i>+foo</i>) is propagated to the result of table
147
136
<b>REGULAR EXPRESSION TABLES</b>
148
This section describes how the table lookups change when
149
the table is given in the form of regular expressions. For
150
a description of regular expression lookup table syntax,
151
see <a href="regexp_table.5.html"><b>regexp_table</b>(5)</a> or <a href="pcre_table.5.html"><b>pcre_table</b>(5)</a>.
153
Each pattern is a regular expression that is applied to
154
the entire address being looked up. Thus, <i>user@domain</i> mail
155
addresses are not broken up into their <i>user</i> and <i>@domain</i>
156
constituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and
159
Patterns are applied in the order as specified in the ta-
160
ble, until a pattern is found that matches the search
163
Results are the same as with indexed file lookups, with
164
the additional feature that parenthesized substrings from
165
the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on.
137
This section describes how the table lookups change when the table is
138
given in the form of regular expressions. For a description of regular
139
expression lookup table syntax, see <a href="regexp_table.5.html"><b>regexp_table</b>(5)</a> or <a href="pcre_table.5.html"><b>pcre_table</b>(5)</a>.
141
Each pattern is a regular expression that is applied to the entire
142
address being looked up. Thus, <i>user@domain</i> mail addresses are not bro-
143
ken up into their <i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i>
144
broken up into <i>user</i> and <i>foo</i>.
146
Patterns are applied in the order as specified in the table, until a
147
pattern is found that matches the search string.
149
Results are the same as with indexed file lookups, with the additional
150
feature that parenthesized substrings from the pattern can be interpo-
151
lated as <b>$1</b>, <b>$2</b> and so on.
167
153
<b>TCP-BASED TABLES</b>
168
This section describes how the table lookups change when
169
lookups are directed to a TCP-based server. For a descrip-
170
tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a>
171
<a href="tcp_table.5.html"><b>ble</b>(5)</a>. This feature is not available up to and including
154
This section describes how the table lookups change when lookups are
155
directed to a TCP-based server. For a description of the TCP
156
client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>. This feature is not
157
available up to and including Postfix version 2.4.
174
Each lookup operation uses the entire address once. Thus,
175
<i>user@domain</i> mail addresses are not broken up into their
176
<i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i> broken
177
up into <i>user</i> and <i>foo</i>.
159
Each lookup operation uses the entire address once. Thus, <i>user@domain</i>
160
mail addresses are not broken up into their <i>user</i> and <i>@domain</i> con-
161
stituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>.
179
163
Results are the same as with indexed file lookups.
182
The table format does not understand quoting conventions.
166
The table format does not understand quoting conventions.
184
168
<b>CONFIGURATION PARAMETERS</b>
185
The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant.
186
The text below provides only a parameter summary. See
187
<a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
169
The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant. The text
170
below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for more
171
details including examples.
189
173
<b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b>
190
What addresses are subject to canonical address
174
What addresses are subject to canonical address mapping.
193
176
<b><a href="postconf.5.html#canonical_maps">canonical_maps</a></b>
194
177
List of canonical mapping tables.
196
179
<b><a href="postconf.5.html#recipient_canonical_maps">recipient_canonical_maps</a></b>
197
Address mapping lookup table for envelope and
198
header recipient addresses.
180
Address mapping lookup table for envelope and header recipient
200
183
<b><a href="postconf.5.html#sender_canonical_maps">sender_canonical_maps</a></b>
201
Address mapping lookup table for envelope and
202
header sender addresses.
184
Address mapping lookup table for envelope and header sender
204
187
<b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b>
205
A list of address rewriting or forwarding mecha-
206
nisms that propagate an address extension from the
207
original address to the result. Specify zero or
208
more of <b>canonical</b>, <b>virtual</b>, <b>alias</b>, <b>forward</b>,
209
<b>include</b>, or <b>generic</b>.
188
A list of address rewriting or forwarding mechanisms that propa-
189
gate an address extension from the original address to the
190
result. Specify zero or more of <b>canonical</b>, <b>virtual</b>, <b>alias</b>, <b>for-</b>
191
<b>ward</b>, <b>include</b>, or <b>generic</b>.
211
193
Other parameters of interest:
213
195
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b>
214
The network interface addresses that this system
215
receives mail on. You need to stop and start Post-
216
fix when this parameter changes.
196
The network interface addresses that this system receives mail
197
on. You need to stop and start Postfix when this parameter
218
200
<b><a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a></b>
219
Rewrite message header addresses in mail from these
220
clients and update incomplete addresses with the
221
domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or $<a href="postconf.5.html#mydomain">mydomain</a>; either don't
222
rewrite message headers from other clients at all,
223
or rewrite message headers and update incomplete
224
addresses with the domain specified in the
225
<a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> parameter.
201
Rewrite message header addresses in mail from these clients and
202
update incomplete addresses with the domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or
203
$<a href="postconf.5.html#mydomain">mydomain</a>; either don't rewrite message headers from other
204
clients at all, or rewrite message headers and update incomplete
205
addresses with the domain specified in the <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_re</a>-
206
<a href="postconf.5.html#remote_header_rewrite_domain">write_domain</a> parameter.
227
208
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>
228
Other interfaces that this machine receives mail on
229
by way of a proxy agent or network address transla-
209
Other interfaces that this machine receives mail on by way of a
210
proxy agent or network address translator.
232
212
<b><a href="postconf.5.html#masquerade_classes">masquerade_classes</a></b>
233
List of address classes subject to masquerading:
234
zero or more of <b>envelope_sender</b>, <b>envelope_recipi-</b>
235
<b>ent</b>, <b>header_sender</b>, <b>header_recipient</b>.
213
List of address classes subject to masquerading: zero or more of
214
<b>envelope_sender</b>, <b>envelope_recipient</b>, <b>header_sender</b>,
215
<b>header_recipient</b>.
237
217
<b><a href="postconf.5.html#masquerade_domains">masquerade_domains</a></b>
238
List of domains that hide their subdomain struc-
218
List of domains that hide their subdomain structure.
241
220
<b><a href="postconf.5.html#masquerade_exceptions">masquerade_exceptions</a></b>
242
List of user names that are not subject to address
221
List of user names that are not subject to address masquerading.
245
223
<b><a href="postconf.5.html#mydestination">mydestination</a></b>
246
List of domains that this mail system considers
224
List of domains that this mail system considers local.
249
226
<b><a href="postconf.5.html#myorigin">myorigin</a></b>
250
227
The domain that is appended to locally-posted mail.
252
229
<b><a href="postconf.5.html#owner_request_special">owner_request_special</a></b>
253
Give special treatment to <b>owner-</b><i>xxx</i> and <i>xxx</i><b>-request</b>
230
Give special treatment to <b>owner-</b><i>xxx</i> and <i>xxx</i><b>-request</b> addresses.
256
232
<b><a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a></b>
257
Don't rewrite message headers from remote clients
258
at all when this parameter is empty; otherwise, re-
259
write message headers and append the specified
260
domain name to incomplete addresses.
233
Don't rewrite message headers from remote clients at all when
234
this parameter is empty; otherwise, rewrite message headers and
235
append the specified domain name to incomplete addresses.
263
238
<a href="cleanup.8.html">cleanup(8)</a>, canonicalize and enqueue mail
added
removed
html/canonical.5.html
