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.
24       Execute  the  command  "postmap  /etc/postfix/canonical"  to rebuild an
25       indexed 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
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
36       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
42       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
49       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
53       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

CASE FOLDING

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

TABLE FORMAT

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

TABLE SEARCH ORDER

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

RESULT ADDRESS REWRITING

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

ADDRESS EXTENSION

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
145       The  propagate_unmatched_extensions  parameter  controls   whether   an
146       unmatched address extension (+foo) is propagated to the result of table
147       lookup.
148

REGULAR EXPRESSION TABLES

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

TCP-BASED TABLES

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
172       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
176       Results are the same as with indexed file lookups.
177

BUGS

179       The table format does not understand quoting conventions.
180

CONFIGURATION PARAMETERS

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

SEE ALSO

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

README FILES

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

LICENSE

268       The Secure Mailer license must be distributed with this software.
269

AUTHOR(S)

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