autoupdate
[postfix-master.git] / postfix-master / canonical.5.html
blobc97f910ace308acabdb466a2d23ebf399d4d05b1
1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3 <html> <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
5 <title> Postfix manual - canonical(5) </title>
6 </head> <body> <pre>
7 CANONICAL(5) CANONICAL(5)
9 <b>NAME</b>
10 canonical - Postfix canonical table format
12 <b>SYNOPSIS</b>
13 <b>postmap /etc/postfix/canonical</b>
15 <b>postmap -q "</b><i>string</i><b>" /etc/postfix/canonical</b>
17 <b>postmap -q - /etc/postfix/canonical</b> &lt;<i>inputfile</i>
19 <b>DESCRIPTION</b>
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
34 indexed files.
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> =
55 static:all".
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.
66 <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.
72 <b>TABLE FORMAT</b>
73 The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows:
75 <i>pattern result</i>
76 When <i>pattern</i> matches a mail address, replace it by
77 the corresponding <i>result</i>.
79 blank lines and comments
80 Empty lines and whitespace-only lines are ignored,
81 as are lines whose first non-whitespace character
82 is a `#'.
84 multi-line text
85 A logical line starts with non-whitespace text. A
86 line that starts with whitespace continues a logi-
87 cal line.
89 <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:
94 <i>user</i>@<i>domain address</i>
95 Replace <i>user</i>@<i>domain</i> by <i>address</i>. This form has the
96 highest precedence.
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.
103 <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>.
109 This form is useful for replacing login names by
110 <i>Firstname.Lastname</i>.
112 @<i>domain address</i>
113 Replace other addresses in <i>domain</i> by <i>address</i>. This
114 form has the lowest precedence.
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.
125 <b>RESULT ADDRESS REWRITING</b>
126 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".
137 <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
141 @<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.
147 <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
157 <i>foo</i>.
159 Patterns are applied in the order as specified in the ta-
160 ble, until a pattern is found that matches the search
161 string.
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.
167 <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
172 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>.
179 Results are the same as with indexed file lookups.
181 <b>BUGS</b>
182 The table format does not understand quoting conventions.
184 <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.
189 <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b>
190 What addresses are subject to canonical address
191 mapping.
193 <b><a href="postconf.5.html#canonical_maps">canonical_maps</a></b>
194 List of canonical mapping tables.
196 <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.
200 <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.
204 <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>.
211 Other parameters of interest:
213 <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.
218 <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.
227 <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-
230 tor.
232 <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>.
237 <b><a href="postconf.5.html#masquerade_domains">masquerade_domains</a></b>
238 List of domains that hide their subdomain struc-
239 ture.
241 <b><a href="postconf.5.html#masquerade_exceptions">masquerade_exceptions</a></b>
242 List of user names that are not subject to address
243 masquerading.
245 <b><a href="postconf.5.html#mydestination">mydestination</a></b>
246 List of domains that this mail system considers
247 local.
249 <b><a href="postconf.5.html#myorigin">myorigin</a></b>
250 The domain that is appended to locally-posted mail.
252 <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>
254 addresses.
256 <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.
262 <b>SEE ALSO</b>
263 <a href="cleanup.8.html">cleanup(8)</a>, canonicalize and enqueue mail
264 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
265 <a href="postconf.5.html">postconf(5)</a>, configuration parameters
266 <a href="virtual.5.html">virtual(5)</a>, virtual aliasing
268 <b>README FILES</b>
269 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
270 <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a>, address rewriting guide
272 <b>LICENSE</b>
273 The Secure Mailer license must be distributed with this
274 software.
276 <b>AUTHOR(S)</b>
277 Wietse Venema
278 IBM T.J. Watson Research
279 P.O. Box 704
280 Yorktown Heights, NY 10598, USA
282 CANONICAL(5)
283 </pre> </body> </html>