1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5<title> Postfix manual - canonical(5) </title> 6</head> <body> <pre> 7CANONICAL(5) CANONICAL(5) 8 9<b>NAME</b> 10 canonical - Postfix canonical table format 11 12<b>SYNOPSIS</b> 13 <b>postmap /etc/postfix/canonical</b> 14 15 <b>postmap -q "</b><i>string</i><b>" /etc/postfix/canonical</b> 16 17 <b>postmap -q - /etc/postfix/canonical</b> <<i>inputfile</i> 18 19<b>DESCRIPTION</b> 20 The optional <a href="canonical.5.html"><b>canonical</b>(5)</a> table specifies an address mapping for local 21 and non-local addresses. The mapping is used by the <a href="cleanup.8.html"><b>cleanup</b>(8)</a> daemon, 22 before mail is stored into the queue. The address mapping is recur- 23 sive. 24 25 Normally, the <a href="canonical.5.html"><b>canonical</b>(5)</a> table is specified as a text file that 26 serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The result, an indexed file 27 in <b>dbm</b> or <b>db</b> format, is used for fast searching by the mail system. 28 Execute the command "<b>postmap /etc/postfix/canonical</b>" to rebuild an 29 indexed file after changing the corresponding text file. 30 31 When the table is provided via other means such as NIS, LDAP or SQL, 32 the same lookups are done as for ordinary indexed files. 33 34 Alternatively, the table can be provided as a regular-expression map 35 where patterns are given as regular expressions, or lookups can be 36 directed to a TCP-based server. In those cases, the lookups are done in 37 a slightly different way as described below under "REGULAR EXPRESSION 38 TABLES" or "TCP-BASED TABLES". 39 40 By default the <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping affects both message header 41 addresses (i.e. addresses that appear inside messages) and message 42 envelope addresses (for example, the addresses that are used in SMTP 43 protocol commands). This is controlled with the <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b> 44 parameter. 45 46 NOTE: Postfix versions 2.2 and later rewrite message headers from 47 remote SMTP clients only if the client matches the <a href="postconf.5.html#local_header_rewrite_clients">local_header_re</a>- 48 <a href="postconf.5.html#local_header_rewrite_clients">write_clients</a> parameter, or if the <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> config- 49 uration parameter specifies a non-empty value. To get the behavior 50 before Postfix 2.2, specify "<a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> = 51 <a href="DATABASE_README.html#types">static</a>:all". 52 53 Typically, one would use the <a href="canonical.5.html"><b>canonical</b>(5)</a> table to replace login names 54 by <i>Firstname.Lastname</i>, or to clean up addresses produced by legacy mail 55 systems. 56 57 The <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping is not to be confused with <i>virtual alias</i> sup- 58 port or with local aliasing. To change the destination but not the 59 headers, use the <a href="virtual.5.html"><b>virtual</b>(5)</a> or <a href="aliases.5.html"><b>aliases</b>(5)</a> map instead. 60 61<b>CASE FOLDING</b> 62 The search string is folded to lowercase before database lookup. As of 63 Postfix 2.3, the search string is not case folded with database types 64 such as <a href="regexp_table.5.html">regexp</a>: or <a href="pcre_table.5.html">pcre</a>: whose lookup fields can match both upper and 65 lower case. 66 67<b>TABLE FORMAT</b> 68 The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows: 69 70 <i>pattern address</i> 71 When <i>pattern</i> matches a mail address, replace it by the corre- 72 sponding <i>address</i>. 73 74 blank lines and comments 75 Empty lines and whitespace-only lines are ignored, as are lines 76 whose first non-whitespace character is a `#'. 77 78 multi-line text 79 A logical line starts with non-whitespace text. A line that 80 starts with whitespace continues a logical line. 81 82<b>TABLE SEARCH ORDER</b> 83 With lookups from indexed files such as DB or DBM, or from networked 84 tables such as NIS, LDAP or SQL, each <i>user</i>@<i>domain</i> query produces a 85 sequence of query patterns as described below. 86 87 Each query pattern is sent to each specified lookup table before trying 88 the next query pattern, until a match is found. 89 90 <i>user</i>@<i>domain address</i> 91 Replace <i>user</i>@<i>domain</i> by <i>address</i>. This form has the highest prece- 92 dence. 93 94 This is useful to clean up addresses produced by legacy mail 95 systems. It can also be used to produce <i>Firstname.Lastname</i> 96 style addresses, but see below for a simpler solution. 97 98 <i>user address</i> 99 Replace <i>user</i>@<i>site</i> by <i>address</i> when <i>site</i> is equal to $<b><a href="postconf.5.html#myorigin">myorigin</a></b>, 100 when <i>site</i> is listed in $<b><a href="postconf.5.html#mydestination">mydestination</a></b>, or when it is listed in 101 $<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b> or $<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>. 102 103 This form is useful for replacing login names by <i>Firstname.Last-</i> 104 <i>name</i>. 105 106 @<i>domain address</i> 107 Replace other addresses in <i>domain</i> by <i>address</i>. This form has the 108 lowest precedence. 109 110 Note: @<i>domain</i> is a wild-card. When this form is applied to 111 recipient addresses, the Postfix SMTP server accepts mail for 112 any recipient in <i>domain</i>, regardless of whether that recipient 113 exists. This may turn your mail system into a backscatter 114 source: Postfix first accepts mail for non-existent recipients 115 and then tries to return that mail as "undeliverable" to the 116 often forged sender address. 117 118 To avoid backscatter with mail for a wild-card domain, replace 119 the wild-card mapping with explicit 1:1 mappings, or add a 120 <a href="postconf.5.html#reject_unverified_recipient">reject_unverified_recipient</a> restriction for that domain: 121 122 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = 123 ... 124 <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> 125 <a href="postconf.5.html#check_recipient_access">check_recipient_access</a> 126 <a href="DATABASE_README.html#types">inline</a>:{example.com=<a href="postconf.5.html#reject_unverified_recipient">reject_unverified_recipient</a>} 127 <a href="postconf.5.html#unverified_recipient_reject_code">unverified_recipient_reject_code</a> = 550 128 129 In the above example, Postfix may contact a remote server if the 130 recipient is rewritten to a remote address. 131 132<b>RESULT ADDRESS REWRITING</b> 133 The lookup result is subject to address rewriting: 134 135 <b>o</b> When the result has the form @<i>otherdomain</i>, the result becomes 136 the same <i>user</i> in <i>otherdomain</i>. 137 138 <b>o</b> When "<b><a href="postconf.5.html#append_at_myorigin">append_at_myorigin</a>=yes</b>", append "<b>@$<a href="postconf.5.html#myorigin">myorigin</a></b>" to addresses 139 without "@domain". 140 141 <b>o</b> When "<b><a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b>", append "<b>.$<a href="postconf.5.html#mydomain">mydomain</a></b>" to addresses 142 without ".domain". 143 144<b>ADDRESS EXTENSION</b> 145 When a mail address localpart contains the optional recipient delimiter 146 (e.g., <i>user+foo</i>@<i>domain</i>), the lookup order becomes: <i>user+foo</i>@<i>domain</i>, 147 <i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and @<i>domain</i>. 148 149 The <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> parameter controls whether an 150 unmatched address extension (<i>+foo</i>) is propagated to the result of table 151 lookup. 152 153<b>REGULAR EXPRESSION TABLES</b> 154 This section describes how the table lookups change when the table is 155 given in the form of regular expressions. For a description of regular 156 expression lookup table syntax, see <a href="regexp_table.5.html"><b>regexp_table</b>(5)</a> or <a href="pcre_table.5.html"><b>pcre_table</b>(5)</a>. 157 158 Each pattern is a regular expression that is applied to the entire 159 address being looked up. Thus, <i>user@domain</i> mail addresses are not bro- 160 ken up into their <i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i> 161 broken up into <i>user</i> and <i>foo</i>. 162 163 Patterns are applied in the order as specified in the table, until a 164 pattern is found that matches the search string. 165 166 Results are the same as with indexed file lookups, with the additional 167 feature that parenthesized substrings from the pattern can be interpo- 168 lated as <b>$1</b>, <b>$2</b> and so on. 169 170<b>TCP-BASED TABLES</b> 171 This section describes how the table lookups change when lookups are 172 directed to a TCP-based server. For a description of the TCP 173 client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>. This feature is not 174 available up to and including Postfix version 2.4. 175 176 Each lookup operation uses the entire address once. Thus, <i>user@domain</i> 177 mail addresses are not broken up into their <i>user</i> and <i>@domain</i> con- 178 stituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. 179 180 Results are the same as with indexed file lookups. 181 182<b>BUGS</b> 183 The table format does not understand quoting conventions. 184 185<b>CONFIGURATION PARAMETERS</b> 186 The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant. The text 187 below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for more 188 details including examples. 189 190 <b><a href="postconf.5.html#canonical_classes">canonical_classes</a> (envelope_sender, envelope_recipient, header_sender,</b> 191 <b>header_recipient)</b> 192 What addresses are subject to <a href="postconf.5.html#canonical_maps">canonical_maps</a> address mapping. 193 194 <b><a href="postconf.5.html#canonical_maps">canonical_maps</a> (empty)</b> 195 Optional address mapping lookup tables for message headers and 196 envelopes. 197 198 <b><a href="postconf.5.html#recipient_canonical_maps">recipient_canonical_maps</a> (empty)</b> 199 Optional address mapping lookup tables for envelope and header 200 recipient addresses. 201 202 <b><a href="postconf.5.html#sender_canonical_maps">sender_canonical_maps</a> (empty)</b> 203 Optional address mapping lookup tables for envelope and header 204 sender addresses. 205 206 <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a> (canonical, virtual)</b> 207 What address lookup tables copy an address extension from the 208 lookup key to the lookup result. 209 210 Other parameters of interest: 211 212 <b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b> 213 The network interface addresses that this mail system receives 214 mail on. 215 216 <b><a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> (<a href="postconf.5.html#permit_inet_interfaces">permit_inet_interfaces</a>)</b> 217 Rewrite message header addresses in mail from these clients and 218 update incomplete addresses with the domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or 219 $<a href="postconf.5.html#mydomain">mydomain</a>; either don't rewrite message headers from other 220 clients at all, or rewrite message headers and update incomplete 221 addresses with the domain specified in the <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_re</a>- 222 <a href="postconf.5.html#remote_header_rewrite_domain">write_domain</a> parameter. 223 224 <b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b> 225 The network interface addresses that this mail system receives 226 mail on by way of a proxy or network address translation unit. 227 228 <b><a href="postconf.5.html#masquerade_classes">masquerade_classes</a> (envelope_sender, header_sender, header_recipient)</b> 229 What addresses are subject to address masquerading. 230 231 <b><a href="postconf.5.html#masquerade_domains">masquerade_domains</a> (empty)</b> 232 Optional list of domains whose subdomain structure will be 233 stripped off in email addresses. 234 235 <b><a href="postconf.5.html#masquerade_exceptions">masquerade_exceptions</a> (empty)</b> 236 Optional list of user names that are not subjected to address 237 masquerading, even when their addresses match $<a href="postconf.5.html#masquerade_domains">masquer</a>- 238 <a href="postconf.5.html#masquerade_domains">ade_domains</a>. 239 240 <b><a href="postconf.5.html#mydestination">mydestination</a> ($<a href="postconf.5.html#myhostname">myhostname</a>, localhost.$<a href="postconf.5.html#mydomain">mydomain</a>, localhost)</b> 241 The list of domains that are delivered via the $<a href="postconf.5.html#local_transport">local_transport</a> 242 mail delivery transport. 243 244 <b><a href="postconf.5.html#myorigin">myorigin</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b> 245 The domain name that locally-posted mail appears to come from, 246 and that locally posted mail is delivered to. 247 248 <b><a href="postconf.5.html#owner_request_special">owner_request_special</a> (yes)</b> 249 Enable special treatment for owner-<i>listname</i> entries in the 250 <a href="aliases.5.html"><b>aliases</b>(5)</a> file, and don't split owner-<i>listname</i> and <i>list-</i> 251 <i>name</i>-request address localparts when the <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> is 252 set to "-". 253 254 <b><a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> (empty)</b> 255 Don't rewrite message headers from remote clients at all when 256 this parameter is empty; otherwise, rewrite message headers and 257 append the specified domain name to incomplete addresses. 258 259<b>SEE ALSO</b> 260 <a href="cleanup.8.html">cleanup(8)</a>, canonicalize and enqueue mail 261 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 262 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 263 <a href="virtual.5.html">virtual(5)</a>, virtual aliasing 264 265<b>README FILES</b> 266 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 267 <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a>, address rewriting guide 268 269<b>LICENSE</b> 270 The Secure Mailer license must be distributed with this software. 271 272<b>AUTHOR(S)</b> 273 Wietse Venema 274 IBM T.J. Watson Research 275 P.O. Box 704 276 Yorktown Heights, NY 10598, USA 277 278 Wietse Venema 279 Google, Inc. 280 111 8th Avenue 281 New York, NY 10011, USA 282 283 CANONICAL(5) 284</pre> </body> </html> 285