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