1CANONICAL(5) File Formats Manual CANONICAL(5)
2
6 canonical - Postfix canonical table format
7
9 postmap /etc/postfix/canonical
10 postmap -q "string" /etc/postfix/canonical
12 postmap -q - /etc/postfix/canonical <inputfile
14
16 The optional canonical(5) table specifies an address mapping for local
17 and non-local addresses. The mapping is used by the cleanup(8) daemon,
18 before mail is stored into the queue. The address mapping is recur‐
19 sive.
20 Normally, the canonical(5) table is specified as a text file that
22 serves as input to the postmap(1) command. The result, an indexed file
23 in dbm or db format, is used for fast searching by the mail system. Ex‐
24 ecute the command "postmap /etc/postfix/canonical" to rebuild an in‐
25 dexed file after changing the corresponding text file.
26 When the table is provided via other means such as NIS, LDAP or SQL,
28 the same lookups are done as for ordinary indexed files.
29 Alternatively, the table can be provided as a regular-expression map
31 where patterns are given as regular expressions, or lookups can be di‐
32 rected to a TCP-based server. In those cases, the lookups are done in a
33 slightly different way as described below under "REGULAR EXPRESSION TA‐
34 BLES" or "TCP-BASED TABLES".
35 By default the canonical(5) mapping affects both message header ad‐
37 dresses (i.e. addresses that appear inside messages) and message enve‐
38 lope addresses (for example, the addresses that are used in SMTP proto‐
39 col commands). This is controlled with the canonical_classes parameter.
40 NOTE: Postfix versions 2.2 and later rewrite message headers from re‐
42 mote SMTP clients only if the client matches the local_header_re‐
43 write_clients parameter, or if the remote_header_rewrite_domain config‐
44 uration parameter specifies a non-empty value. To get the behavior be‐
45 fore Postfix 2.2, specify "local_header_rewrite_clients = static:all".
46 Typically, one would use the canonical(5) table to replace login names
48 by Firstname.Lastname, or to clean up addresses produced by legacy mail
49 systems.
50 The canonical(5) mapping is not to be confused with virtual alias sup‐
52 port or with local aliasing. To change the destination but not the
53 headers, use the virtual(5) or aliases(5) map instead.
54
56 The search string is folded to lowercase before database lookup. As of
57 Postfix 2.3, the search string is not case folded with database types
58 such as regexp: or pcre: whose lookup fields can match both upper and
59 lower case.
60
62 The input format for the postmap(1) command is as follows:
63 pattern address
65 When pattern matches a mail address, replace it by the corre‐
66 sponding address.
67 blank lines and comments
69 Empty lines and whitespace-only lines are ignored, as are lines
70 whose first non-whitespace character is a `#'.
71 multi-line text
73 A logical line starts with non-whitespace text. A line that
74 starts with whitespace continues a logical line.
75
77 With lookups from indexed files such as DB or DBM, or from networked
78 tables such as NIS, LDAP or SQL, each user@domain query produces a se‐
79 quence of query patterns as described below.
80 Each query pattern is sent to each specified lookup table before trying
82 the next query pattern, until a match is found.
83 user@domain address
85 Replace user@domain by address. This form has the highest prece‐
86 dence.
87 This is useful to clean up addresses produced by legacy mail
89 systems. It can also be used to produce Firstname.Lastname
90 style addresses, but see below for a simpler solution.
91 user address
93 Replace user@site by address when site is equal to $myorigin,
94 when site is listed in $mydestination, or when it is listed in
95 $inet_interfaces or $proxy_interfaces.
96 This form is useful for replacing login names by Firstname.Last‐
98 name.
99 @domain address
101 Replace other addresses in domain by address. This form has the
102 lowest precedence.
103 Note: @domain is a wild-card. When this form is applied to re‐
105 cipient addresses, the Postfix SMTP server accepts mail for any
106 recipient in domain, regardless of whether that recipient ex‐
107 ists. This may turn your mail system into a backscatter source:
108 Postfix first accepts mail for non-existent recipients and then
109 tries to return that mail as "undeliverable" to the often forged
110 sender address.
111 To avoid backscatter with mail for a wild-card domain, replace
113 the wild-card mapping with explicit 1:1 mappings, or add a re‐
114 ject_unverified_recipient restriction for that domain:
115 smtpd_recipient_restrictions =
117 ...
118 reject_unauth_destination
119 check_recipient_access
120 inline:{example.com=reject_unverified_recipient}
121 unverified_recipient_reject_code = 550
122 In the above example, Postfix may contact a remote server if the
124 recipient is rewritten to a remote address.
125
127 The lookup result is subject to address rewriting:
128 • When the result has the form @otherdomain, the result becomes
130 the same user in otherdomain.
131 • When "append_at_myorigin=yes", append "@$myorigin" to addresses
133 without "@domain".
134 • When "append_dot_mydomain=yes", append ".$mydomain" to addresses
136 without ".domain".
137
139 When a mail address localpart contains the optional recipient delimiter
140 (e.g., user+foo@domain), the lookup order becomes: user+foo@domain,
141 user@domain, user+foo, user, and @domain.
142 The propagate_unmatched_extensions parameter controls whether an un‐
144 matched address extension (+foo) is propagated to the result of table
145 lookup.
146
148 This section describes how the table lookups change when the table is
149 given in the form of regular expressions. For a description of regular
150 expression lookup table syntax, see regexp_table(5) or pcre_table(5).
151 Each pattern is a regular expression that is applied to the entire ad‐
153 dress being looked up. Thus, user@domain mail addresses are not broken
154 up into their user and @domain constituent parts, nor is user+foo bro‐
155 ken up into user and foo.
156 Patterns are applied in the order as specified in the table, until a
158 pattern is found that matches the search string.
159 Results are the same as with indexed file lookups, with the additional
161 feature that parenthesized substrings from the pattern can be interpo‐
162 lated as $1, $2 and so on.
163
165 This section describes how the table lookups change when lookups are
166 directed to a TCP-based server. For a description of the TCP
167 client/server lookup protocol, see tcp_table(5). This feature is not
168 available up to and including Postfix version 2.4.
169 Each lookup operation uses the entire address once. Thus, user@domain
171 mail addresses are not broken up into their user and @domain con‐
172 stituent parts, nor is user+foo broken up into user and foo.
173 Results are the same as with indexed file lookups.
175
177 The table format does not understand quoting conventions.
178
180 The following main.cf parameters are especially relevant. The text be‐
181 low provides only a parameter summary. See postconf(5) for more details
182 including examples.
183 canonical_classes (envelope_sender, envelope_recipient, header_sender,
185 header_recipient)
186 What addresses are subject to canonical_maps address mapping.
187 canonical_maps (empty)
189 Optional address mapping lookup tables for message headers and
190 envelopes.
191 recipient_canonical_maps (empty)
193 Optional address mapping lookup tables for envelope and header
194 recipient addresses.
195 sender_canonical_maps (empty)
197 Optional address mapping lookup tables for envelope and header
198 sender addresses.
199 propagate_unmatched_extensions (canonical, virtual)
201 What address lookup tables copy an address extension from the
202 lookup key to the lookup result.
203 Other parameters of interest:
205 inet_interfaces (all)
207 The network interface addresses that this mail system receives
208 mail on.
209 local_header_rewrite_clients (permit_inet_interfaces)
211 Rewrite message header addresses in mail from these clients and
212 update incomplete addresses with the domain name in $myorigin or
213 $mydomain; either don't rewrite message headers from other
214 clients at all, or rewrite message headers and update incomplete
215 addresses with the domain specified in the remote_header_re‐
216 write_domain parameter.
217 proxy_interfaces (empty)
219 The network interface addresses that this mail system receives
220 mail on by way of a proxy or network address translation unit.
221 masquerade_classes (envelope_sender, header_sender, header_recipient)
223 What addresses are subject to address masquerading.
224 masquerade_domains (empty)
226 Optional list of domains whose subdomain structure will be
227 stripped off in email addresses.
228 masquerade_exceptions (empty)
230 Optional list of user names that are not subjected to address
231 masquerading, even when their addresses match $masquerade_do‐
232 mains.
233 mydestination ($myhostname, localhost.$mydomain, localhost)
235 The list of domains that are delivered via the $local_transport
236 mail delivery transport.
237 myorigin ($myhostname)
239 The domain name that locally-posted mail appears to come from,
240 and that locally posted mail is delivered to.
241 owner_request_special (yes)
243 Enable special treatment for owner-listname entries in the
244 aliases(5) file, and don't split owner-listname and listname-re‐
245 quest address localparts when the recipient_delimiter is set to
246 "-".
247 remote_header_rewrite_domain (empty)
249 Don't rewrite message headers from remote clients at all when
250 this parameter is empty; otherwise, rewrite message headers and
251 append the specified domain name to incomplete addresses.
252
254 cleanup(8), canonicalize and enqueue mail
255 postmap(1), Postfix lookup table manager
256 postconf(5), configuration parameters
257 virtual(5), virtual aliasing
258
260 Use "postconf readme_directory" or "postconf html_directory" to locate
261 this information.
262 DATABASE_README, Postfix lookup table overview
263 ADDRESS_REWRITING_README, address rewriting guide
264
266 The Secure Mailer license must be distributed with this software.
267
269 Wietse Venema
270 IBM T.J. Watson Research
271 P.O. Box 704
272 Yorktown Heights, NY 10598, USA
273 Wietse Venema
275 Google, Inc.
276 111 8th Avenue
277 New York, NY 10011, USA
278 CANONICAL(5)