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, patterns are tried in the order as
81 listed below:
82 user@domain address
84 Replace user@domain by address. This form has the highest prece‐
85 dence.
86 This is useful to clean up addresses produced by legacy mail
88 systems. It can also be used to produce Firstname.Lastname
89 style addresses, but see below for a simpler solution.
90 user address
92 Replace user@site by address when site is equal to $myorigin,
93 when site is listed in $mydestination, or when it is listed in
94 $inet_interfaces or $proxy_interfaces.
95 This form is useful for replacing login names by Firstname.Last‐
97 name.
98 @domain address
100 Replace other addresses in domain by address. This form has the
101 lowest precedence.
102 Note: @domain is a wild-card. When this form is applied to
104 recipient addresses, the Postfix SMTP server accepts mail for
105 any recipient in domain, regardless of whether that recipient
106 exists. This may turn your mail system into a backscatter
107 source: Postfix first accepts mail for non-existent recipients
108 and then tries to return that mail as "undeliverable" to the
109 often forged sender address.
110
112 The lookup result is subject to address rewriting:
113 · When the result has the form @otherdomain, the result becomes
115 the same user in otherdomain.
116 · When "append_at_myorigin=yes", append "@$myorigin" to addresses
118 without "@domain".
119 · When "append_dot_mydomain=yes", append ".$mydomain" to addresses
121 without ".domain".
122
124 When a mail address localpart contains the optional recipient delimiter
125 (e.g., user+foo@domain), the lookup order becomes: user+foo@domain,
126 user@domain, user+foo, user, and @domain.
127 The propagate_unmatched_extensions parameter controls whether an
129 unmatched address extension (+foo) is propagated to the result of table
130 lookup.
131
133 This section describes how the table lookups change when the table is
134 given in the form of regular expressions. For a description of regular
135 expression lookup table syntax, see regexp_table(5) or pcre_table(5).
136 Each pattern is a regular expression that is applied to the entire
138 address being looked up. Thus, user@domain mail addresses are not bro‐
139 ken up into their user and @domain constituent parts, nor is user+foo
140 broken up into user and foo.
141 Patterns are applied in the order as specified in the table, until a
143 pattern is found that matches the search string.
144 Results are the same as with indexed file lookups, with the additional
146 feature that parenthesized substrings from the pattern can be interpo‐
147 lated as $1, $2 and so on.
148
150 This section describes how the table lookups change when lookups are
151 directed to a TCP-based server. For a description of the TCP
152 client/server lookup protocol, see tcp_table(5). This feature is not
153 available up to and including Postfix version 2.4.
154 Each lookup operation uses the entire address once. Thus, user@domain
156 mail addresses are not broken up into their user and @domain con‐
157 stituent parts, nor is user+foo broken up into user and foo.
158 Results are the same as with indexed file lookups.
160
162 The table format does not understand quoting conventions.
163
165 The following main.cf parameters are especially relevant. The text
166 below provides only a parameter summary. See postconf(5) for more
167 details including examples.
168 canonical_classes
170 What addresses are subject to canonical address mapping.
171 canonical_maps
173 List of canonical mapping tables.
174 recipient_canonical_maps
176 Address mapping lookup table for envelope and header recipient
177 addresses.
178 sender_canonical_maps
180 Address mapping lookup table for envelope and header sender
181 addresses.
182 propagate_unmatched_extensions
184 A list of address rewriting or forwarding mechanisms that propa‐
185 gate an address extension from the original address to the
186 result. Specify zero or more of canonical, virtual, alias, for‐
187 ward, include, or generic.
188 Other parameters of interest:
190 inet_interfaces
192 The network interface addresses that this system receives mail
193 on. You need to stop and start Postfix when this parameter
194 changes.
195 local_header_rewrite_clients
197 Rewrite message header addresses in mail from these clients and
198 update incomplete addresses with the domain name in $myorigin or
199 $mydomain; either don't rewrite message headers from other
200 clients at all, or rewrite message headers and update incomplete
201 addresses with the domain specified in the remote_header_re‐
202 write_domain parameter.
203 proxy_interfaces
205 Other interfaces that this machine receives mail on by way of a
206 proxy agent or network address translator.
207 masquerade_classes
209 List of address classes subject to masquerading: zero or more of
210 envelope_sender, envelope_recipient, header_sender,
211 header_recipient.
212 masquerade_domains
214 List of domains that hide their subdomain structure.
215 masquerade_exceptions
217 List of user names that are not subject to address masquerading.
218 mydestination
220 List of domains that this mail system considers local.
221 myorigin
223 The domain that is appended to locally-posted mail.
224 owner_request_special
226 Give special treatment to owner-xxx and xxx-request addresses.
227 remote_header_rewrite_domain
229 Don't rewrite message headers from remote clients at all when
230 this parameter is empty; otherwise, rewrite message headers and
231 append the specified domain name to incomplete addresses.
232
234 cleanup(8), canonicalize and enqueue mail
235 postmap(1), Postfix lookup table manager
236 postconf(5), configuration parameters
237 virtual(5), virtual aliasing
238
240 Use "postconf readme_directory" or "postconf html_directory" to locate
241 this information.
242 DATABASE_README, Postfix lookup table overview
243 ADDRESS_REWRITING_README, address rewriting guide
244
246 The Secure Mailer license must be distributed with this software.
247
249 Wietse Venema
250 IBM T.J. Watson Research
251 P.O. Box 704
252 Yorktown Heights, NY 10598, USA
253 CANONICAL(5)