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 result
67 When pattern matches a mail address, replace it by the corre‐
68 sponding result.
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
115 The lookup result is subject to address rewriting:
116 · When the result has the form @otherdomain, the result becomes
118 the same user in otherdomain.
119 · When "append_at_myorigin=yes", append "@$myorigin" to addresses
121 without "@domain".
122 · When "append_dot_mydomain=yes", append ".$mydomain" to addresses
124 without ".domain".
125
127 When a mail address localpart contains the optional recipient delimiter
128 (e.g., user+foo@domain), the lookup order becomes: user+foo@domain,
129 user@domain, user+foo, user, and @domain.
130 The propagate_unmatched_extensions parameter controls whether an
132 unmatched address extension (+foo) is propagated to the result of table
133 lookup.
134
136 This section describes how the table lookups change when the table is
137 given in the form of regular expressions. For a description of regular
138 expression lookup table syntax, see regexp_table(5) or pcre_table(5).
139 Each pattern is a regular expression that is applied to the entire
141 address being looked up. Thus, user@domain mail addresses are not bro‐
142 ken up into their user and @domain constituent parts, nor is user+foo
143 broken up into user and foo.
144 Patterns are applied in the order as specified in the table, until a
146 pattern is found that matches the search string.
147 Results are the same as with indexed file lookups, with the additional
149 feature that parenthesized substrings from the pattern can be interpo‐
150 lated as $1, $2 and so on.
151
153 This section describes how the table lookups change when lookups are
154 directed to a TCP-based server. For a description of the TCP
155 client/server lookup protocol, see tcp_table(5). This feature is not
156 available up to and including Postfix version 2.4.
157 Each lookup operation uses the entire address once. Thus, user@domain
159 mail addresses are not broken up into their user and @domain con‐
160 stituent parts, nor is user+foo broken up into user and foo.
161 Results are the same as with indexed file lookups.
163
165 The table format does not understand quoting conventions.
166
168 The following main.cf parameters are especially relevant. The text
169 below provides only a parameter summary. See postconf(5) for more
170 details including examples.
171 canonical_classes
173 What addresses are subject to canonical address mapping.
174 canonical_maps
176 List of canonical mapping tables.
177 recipient_canonical_maps
179 Address mapping lookup table for envelope and header recipient
180 addresses.
181 sender_canonical_maps
183 Address mapping lookup table for envelope and header sender
184 addresses.
185 propagate_unmatched_extensions
187 A list of address rewriting or forwarding mechanisms that propa‐
188 gate an address extension from the original address to the
189 result. Specify zero or more of canonical, virtual, alias, for‐
190 ward, include, or generic.
191 Other parameters of interest:
193 inet_interfaces
195 The network interface addresses that this system receives mail
196 on. You need to stop and start Postfix when this parameter
197 changes.
198 local_header_rewrite_clients
200 Rewrite message header addresses in mail from these clients and
201 update incomplete addresses with the domain name in $myorigin or
202 $mydomain; either don't rewrite message headers from other
203 clients at all, or rewrite message headers and update incomplete
204 addresses with the domain specified in the remote_header_re‐
205 write_domain parameter.
206 proxy_interfaces
208 Other interfaces that this machine receives mail on by way of a
209 proxy agent or network address translator.
210 masquerade_classes
212 List of address classes subject to masquerading: zero or more of
213 envelope_sender, envelope_recipient, header_sender,
214 header_recipient.
215 masquerade_domains
217 List of domains that hide their subdomain structure.
218 masquerade_exceptions
220 List of user names that are not subject to address masquerading.
221 mydestination
223 List of domains that this mail system considers local.
224 myorigin
226 The domain that is appended to locally-posted mail.
227 owner_request_special
229 Give special treatment to owner-xxx and xxx-request addresses.
230 remote_header_rewrite_domain
232 Don't rewrite message headers from remote clients at all when
233 this parameter is empty; otherwise, rewrite message headers and
234 append the specified domain name to incomplete addresses.
235
237 cleanup(8), canonicalize and enqueue mail
238 postmap(1), Postfix lookup table manager
239 postconf(5), configuration parameters
240 virtual(5), virtual aliasing
241
243 Use "postconf readme_directory" or "postconf html_directory" to locate
244 this information.
245 DATABASE_README, Postfix lookup table overview
246 ADDRESS_REWRITING_README, address rewriting guide
247
249 The Secure Mailer license must be distributed with this software.
250
252 Wietse Venema
253 IBM T.J. Watson Research
254 P.O. Box 704
255 Yorktown Heights, NY 10598, USA
256 CANONICAL(5)