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.
24 Execute the command "postmap /etc/postfix/canonical" to rebuild an
25 indexed 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
32 directed to TCP-based server. In those cases, the lookups are done in a
33 slightly different way as described below under "REGULAR EXPRESSION
34 TABLES" or "TCP-BASED TABLES".
35 By default the canonical(5) mapping affects both message header
37 addresses (i.e. addresses that appear inside messages) and message
38 envelope addresses (for example, the addresses that are used in SMTP
39 protocol commands). This is controlled with the canonical_classes
40 parameter.
41 NOTE: Postfix versions 2.2 and later rewrite message headers from
43 remote SMTP clients only if the client matches the local_header_re‐
44 write_clients parameter, or if the remote_header_rewrite_domain config‐
45 uration parameter specifies a non-empty value. To get the behavior
46 before Postfix 2.2, specify "local_header_rewrite_clients =
47 static:all".
48 Typically, one would use the canonical(5) table to replace login names
50 by Firstname.Lastname, or to clean up addresses produced by legacy mail
51 systems.
52 The canonical(5) mapping is not to be confused with virtual alias sup‐
54 port or with local aliasing. To change the destination but not the
55 headers, use the virtual(5) or aliases(5) map instead.
56
58 The search string is folded to lowercase before database lookup. As of
59 Postfix 2.3, the search string is not case folded with database types
60 such as regexp: or pcre: whose lookup fields can match both upper and
61 lower case.
62
64 The input format for the postmap(1) command is as follows:
65 pattern address
67 When pattern matches a mail address, replace it by the corre‐
68 sponding address.
69 blank lines and comments
71 Empty lines and whitespace-only lines are ignored, as are lines
72 whose first non-whitespace character is a `#'.
73 multi-line text
75 A logical line starts with non-whitespace text. A line that
76 starts with whitespace continues a logical line.
77
79 With lookups from indexed files such as DB or DBM, or from networked
80 tables such as NIS, LDAP or SQL, each user@domain query produces a
81 sequence of query patterns as described below.
82 Each query pattern is sent to each specified lookup table before trying
84 the next query pattern, until a match is found.
85 user@domain address
87 Replace user@domain by address. This form has the highest prece‐
88 dence.
89 This is useful to clean up addresses produced by legacy mail
91 systems. It can also be used to produce Firstname.Lastname
92 style addresses, but see below for a simpler solution.
93 user address
95 Replace user@site by address when site is equal to $myorigin,
96 when site is listed in $mydestination, or when it is listed in
97 $inet_interfaces or $proxy_interfaces.
98 This form is useful for replacing login names by Firstname.Last‐
100 name.
101 @domain address
103 Replace other addresses in domain by address. This form has the
104 lowest precedence.
105 Note: @domain is a wild-card. When this form is applied to
107 recipient addresses, the Postfix SMTP server accepts mail for
108 any recipient in domain, regardless of whether that recipient
109 exists. This may turn your mail system into a backscatter
110 source: Postfix first accepts mail for non-existent recipients
111 and then tries to return that mail as "undeliverable" to the
112 often forged sender address.
113 To avoid backscatter with mail for a wild-card domain, replace
115 the wild-card mapping with explicit 1:1 mappings, or add a
116 reject_unverified_recipient restriction for that domain:
117 smtpd_recipient_restrictions =
119 ...
120 reject_unauth_destination
121 check_recipient_access
122 inline:{example.com=reject_unverified_recipient}
123 unverified_recipient_reject_code = 550
124 In the above example, Postfix may contact a remote server if the
126 recipient is rewritten to a remote address.
127
129 The lookup result is subject to address rewriting:
130 · When the result has the form @otherdomain, the result becomes
132 the same user in otherdomain.
133 · When "append_at_myorigin=yes", append "@$myorigin" to addresses
135 without "@domain".
136 · When "append_dot_mydomain=yes", append ".$mydomain" to addresses
138 without ".domain".
139
141 When a mail address localpart contains the optional recipient delimiter
142 (e.g., user+foo@domain), the lookup order becomes: user+foo@domain,
143 user@domain, user+foo, user, and @domain.
144 The propagate_unmatched_extensions parameter controls whether an
146 unmatched address extension (+foo) is propagated to the result of table
147 lookup.
148
150 This section describes how the table lookups change when the table is
151 given in the form of regular expressions. For a description of regular
152 expression lookup table syntax, see regexp_table(5) or pcre_table(5).
153 Each pattern is a regular expression that is applied to the entire
155 address being looked up. Thus, user@domain mail addresses are not bro‐
156 ken up into their user and @domain constituent parts, nor is user+foo
157 broken up into user and foo.
158 Patterns are applied in the order as specified in the table, until a
160 pattern is found that matches the search string.
161 Results are the same as with indexed file lookups, with the additional
163 feature that parenthesized substrings from the pattern can be interpo‐
164 lated as $1, $2 and so on.
165
167 This section describes how the table lookups change when lookups are
168 directed to a TCP-based server. For a description of the TCP
169 client/server lookup protocol, see tcp_table(5). This feature is not
170 available up to and including Postfix version 2.4.
171 Each lookup operation uses the entire address once. Thus, user@domain
173 mail addresses are not broken up into their user and @domain con‐
174 stituent parts, nor is user+foo broken up into user and foo.
175 Results are the same as with indexed file lookups.
177
179 The table format does not understand quoting conventions.
180
182 The following main.cf parameters are especially relevant. The text
183 below provides only a parameter summary. See postconf(5) for more
184 details including examples.
185 canonical_classes (envelope_sender, envelope_recipient, header_sender,
187 header_recipient)
188 What addresses are subject to canonical_maps address mapping.
189 canonical_maps (empty)
191 Optional address mapping lookup tables for message headers and
192 envelopes.
193 recipient_canonical_maps (empty)
195 Optional address mapping lookup tables for envelope and header
196 recipient addresses.
197 sender_canonical_maps (empty)
199 Optional address mapping lookup tables for envelope and header
200 sender addresses.
201 propagate_unmatched_extensions (canonical, virtual)
203 What address lookup tables copy an address extension from the
204 lookup key to the lookup result.
205 Other parameters of interest:
207 inet_interfaces (all)
209 The network interface addresses that this mail system receives
210 mail on.
211 local_header_rewrite_clients (permit_inet_interfaces)
213 Rewrite message header addresses in mail from these clients and
214 update incomplete addresses with the domain name in $myorigin or
215 $mydomain; either don't rewrite message headers from other
216 clients at all, or rewrite message headers and update incomplete
217 addresses with the domain specified in the remote_header_re‐
218 write_domain parameter.
219 proxy_interfaces (empty)
221 The network interface addresses that this mail system receives
222 mail on by way of a proxy or network address translation unit.
223 masquerade_classes (envelope_sender, header_sender, header_recipient)
225 What addresses are subject to address masquerading.
226 masquerade_domains (empty)
228 Optional list of domains whose subdomain structure will be
229 stripped off in email addresses.
230 masquerade_exceptions (empty)
232 Optional list of user names that are not subjected to address
233 masquerading, even when their address matches $masquer‐
234 ade_domains.
235 mydestination ($myhostname, localhost.$mydomain, localhost)
237 The list of domains that are delivered via the $local_transport
238 mail delivery transport.
239 myorigin ($myhostname)
241 The domain name that locally-posted mail appears to come from,
242 and that locally posted mail is delivered to.
243 owner_request_special (yes)
245 Enable special treatment for owner-listname entries in the
246 aliases(5) file, and don't split owner-listname and list‐
247 name-request address localparts when the recipient_delimiter is
248 set to "-".
249 remote_header_rewrite_domain (empty)
251 Don't rewrite message headers from remote clients at all when
252 this parameter is empty; otherwise, rewrite message headers and
253 append the specified domain name to incomplete addresses.
254
256 cleanup(8), canonicalize and enqueue mail
257 postmap(1), Postfix lookup table manager
258 postconf(5), configuration parameters
259 virtual(5), virtual aliasing
260
262 Use "postconf readme_directory" or "postconf html_directory" to locate
263 this information.
264 DATABASE_README, Postfix lookup table overview
265 ADDRESS_REWRITING_README, address rewriting guide
266
268 The Secure Mailer license must be distributed with this software.
269
271 Wietse Venema
272 IBM T.J. Watson Research
273 P.O. Box 704
274 Yorktown Heights, NY 10598, USA
275 Wietse Venema
277 Google, Inc.
278 111 8th Avenue
279 New York, NY 10011, USA
280 CANONICAL(5)