1CANONICAL(5)                  File Formats Manual                 CANONICAL(5)
2
3
4

NAME

6       canonical - Postfix canonical table format
7

SYNOPSIS

9       postmap /etc/postfix/canonical
10
11       postmap -q "string" /etc/postfix/canonical
12
13       postmap -q - /etc/postfix/canonical <inputfile
14

DESCRIPTION

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
21       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
27       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
30       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
36       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
41       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
47       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
51       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

CASE FOLDING

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

TABLE FORMAT

62       The input format for the postmap(1) command is as follows:
63
64       pattern address
65              When  pattern  matches  a mail address, replace it by the corre‐
66              sponding address.
67
68       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
72       multi-line text
73              A  logical  line  starts  with  non-whitespace text. A line that
74              starts with whitespace continues a logical line.
75

TABLE SEARCH ORDER

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
81       Each query pattern is sent to each specified lookup table before trying
82       the next query pattern, until a match is found.
83
84       user@domain address
85              Replace user@domain by address. This form has the highest prece‐
86              dence.
87
88              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
92       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
97              This form is useful for replacing login names by Firstname.Last‐
98              name.
99
100       @domain address
101              Replace other addresses in domain by address.  This form has the
102              lowest precedence.
103
104              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
112              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
116                  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
123              In the above example, Postfix may contact a remote server if the
124              recipient is rewritten to a remote address.
125

RESULT ADDRESS REWRITING

127       The lookup result is subject to address rewriting:
128
129       •      When  the  result  has the form @otherdomain, the result becomes
130              the same user in otherdomain.
131
132       •      When "append_at_myorigin=yes", append "@$myorigin" to  addresses
133              without "@domain".
134
135       •      When "append_dot_mydomain=yes", append ".$mydomain" to addresses
136              without ".domain".
137

ADDRESS EXTENSION

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
143       The propagate_unmatched_extensions parameter controls  whether  an  un‐
144       matched  address  extension (+foo) is propagated to the result of table
145       lookup.
146

REGULAR EXPRESSION TABLES

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
152       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
157       Patterns  are  applied  in the order as specified in the table, until a
158       pattern is found that matches the search string.
159
160       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

TCP-BASED TABLES

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
170       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
174       Results are the same as with indexed file lookups.
175

BUGS

177       The table format does not understand quoting conventions.
178

CONFIGURATION PARAMETERS

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
184       canonical_classes  (envelope_sender, envelope_recipient, header_sender,
185       header_recipient)
186              What addresses are subject to canonical_maps address mapping.
187
188       canonical_maps (empty)
189              Optional address mapping lookup tables for message  headers  and
190              envelopes.
191
192       recipient_canonical_maps (empty)
193              Optional  address  mapping lookup tables for envelope and header
194              recipient addresses.
195
196       sender_canonical_maps (empty)
197              Optional address mapping lookup tables for envelope  and  header
198              sender addresses.
199
200       propagate_unmatched_extensions (canonical, virtual)
201              What  address  lookup  tables copy an address extension from the
202              lookup key to the lookup result.
203
204       Other parameters of interest:
205
206       inet_interfaces (all)
207              The network interface addresses that this mail  system  receives
208              mail on.
209
210       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
218       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
222       masquerade_classes (envelope_sender, header_sender, header_recipient)
223              What addresses are subject to address masquerading.
224
225       masquerade_domains (empty)
226              Optional  list  of  domains  whose  subdomain  structure will be
227              stripped off in email addresses.
228
229       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
234       mydestination ($myhostname, localhost.$mydomain, localhost)
235              The list of domains that are delivered via the  $local_transport
236              mail delivery transport.
237
238       myorigin ($myhostname)
239              The  domain  name that locally-posted mail appears to come from,
240              and that locally posted mail is delivered to.
241
242       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
248       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

SEE ALSO

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

README FILES

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

LICENSE

266       The Secure Mailer license must be distributed with this software.
267

AUTHOR(S)

269       Wietse Venema
270       IBM T.J. Watson Research
271       P.O. Box 704
272       Yorktown Heights, NY 10598, USA
273
274       Wietse Venema
275       Google, Inc.
276       111 8th Avenue
277       New York, NY 10011, USA
278
279
280
281                                                                  CANONICAL(5)
Impressum