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=us-ascii"> 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 map- 21 ping for local and non-local addresses. The mapping is 22 used by the <a href="cleanup.8.html"><b>cleanup</b>(8)</a> daemon, before mail is stored into 23 the queue. The address mapping is recursive. 24 25 Normally, the <a href="canonical.5.html"><b>canonical</b>(5)</a> table is specified as a text 26 file that serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The 27 result, an indexed file in <b>dbm</b> or <b>db</b> format, is used for 28 fast searching by the mail system. Execute the command 29 "<b>postmap /etc/postfix/canonical</b>" to rebuild an indexed 30 file after changing the corresponding text file. 31 32 When the table is provided via other means such as NIS, 33 LDAP or SQL, the same lookups are done as for ordinary 34 indexed files. 35 36 Alternatively, the table can be provided as a regular- 37 expression map where patterns are given as regular expres- 38 sions, or lookups can be directed to TCP-based server. In 39 those cases, the lookups are done in a slightly different 40 way as described below under "REGULAR EXPRESSION TABLES" 41 or "TCP-BASED TABLES". 42 43 By default the <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping affects both message 44 header addresses (i.e. addresses that appear inside mes- 45 sages) and message envelope addresses (for example, the 46 addresses that are used in SMTP protocol commands). This 47 is controlled with the <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b> parameter. 48 49 NOTE: Postfix versions 2.2 and later rewrite message head- 50 ers from remote SMTP clients only if the client matches 51 the <a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> parameter, or if the 52 <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> configuration parameter spec- 53 ifies a non-empty value. To get the behavior before Post- 54 fix 2.2, specify "<a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> = 55 static:all". 56 57 Typically, one would use the <a href="canonical.5.html"><b>canonical</b>(5)</a> table to replace 58 login names by <i>Firstname.Lastname</i>, or to clean up 59 addresses produced by legacy mail systems. 60 61 The <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping is not to be confused with <i>vir-</i> 62 <i>tual alias</i> support or with local aliasing. To change the 63 destination but not the headers, use the <a href="virtual.5.html"><b>virtual</b>(5)</a> or 64 <a href="aliases.5.html"><b>aliases</b>(5)</a> map instead. 65 66<b>CASE FOLDING</b> 67 The search string is folded to lowercase before database 68 lookup. As of Postfix 2.3, the search string is not case 69 folded with database types such as <a href="regexp_table.5.html">regexp</a>: or <a href="pcre_table.5.html">pcre</a>: whose 70 lookup fields can match both upper and lower case. 71 72<b>TABLE FORMAT</b> 73 The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows: 74 75 <i>pattern result</i> 76 When <i>pattern</i> matches a mail address, replace it by 77 the corresponding <i>result</i>. 78 79 blank lines and comments 80 Empty lines and whitespace-only lines are ignored, 81 as are lines whose first non-whitespace character 82 is a `#'. 83 84 multi-line text 85 A logical line starts with non-whitespace text. A 86 line that starts with whitespace continues a logi- 87 cal line. 88 89<b>TABLE SEARCH ORDER</b> 90 With lookups from indexed files such as DB or DBM, or from 91 networked tables such as NIS, LDAP or SQL, patterns are 92 tried in the order as listed below: 93 94 <i>user</i>@<i>domain address</i> 95 Replace <i>user</i>@<i>domain</i> by <i>address</i>. This form has the 96 highest precedence. 97 98 This is useful to clean up addresses produced by 99 legacy mail systems. It can also be used to pro- 100 duce <i>Firstname.Lastname</i> style addresses, but see 101 below for a simpler solution. 102 103 <i>user address</i> 104 Replace <i>user</i>@<i>site</i> by <i>address</i> when <i>site</i> is equal to 105 $<b><a href="postconf.5.html#myorigin">myorigin</a></b>, when <i>site</i> is listed in $<b><a href="postconf.5.html#mydestination">mydestination</a></b>, 106 or when it is listed in $<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b> or 107 $<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>. 108 109 This form is useful for replacing login names by 110 <i>Firstname.Lastname</i>. 111 112 @<i>domain address</i> 113 Replace other addresses in <i>domain</i> by <i>address</i>. This 114 form has the lowest precedence. 115 116 Note: @<i>domain</i> is a wild-card. When this form is 117 applied to recipient addresses, the Postfix SMTP 118 server accepts mail for any recipient in <i>domain</i>, 119 regardless of whether that recipient exists. This 120 may turn your mail system into a backscatter 121 source: Postfix first accepts mail for non-existent 122 recipients and then tries to return that mail as 123 "undeliverable" to the often forged sender address. 124 125<b>RESULT ADDRESS REWRITING</b> 126 The lookup result is subject to address rewriting: 127 128 <b>o</b> When the result has the form @<i>otherdomain</i>, the 129 result becomes the same <i>user</i> in <i>otherdomain</i>. 130 131 <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>" 132 to addresses without "@domain". 133 134 <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>" 135 to addresses without ".domain". 136 137<b>ADDRESS EXTENSION</b> 138 When a mail address localpart contains the optional recip- 139 ient delimiter (e.g., <i>user+foo</i>@<i>domain</i>), the lookup order 140 becomes: <i>user+foo</i>@<i>domain</i>, <i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and 141 @<i>domain</i>. 142 143 The <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> parameter controls 144 whether an unmatched address extension (<i>+foo</i>) is propa- 145 gated to the result of table lookup. 146 147<b>REGULAR EXPRESSION TABLES</b> 148 This section describes how the table lookups change when 149 the table is given in the form of regular expressions. For 150 a description of regular expression lookup table syntax, 151 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>. 152 153 Each pattern is a regular expression that is applied to 154 the entire address being looked up. Thus, <i>user@domain</i> mail 155 addresses are not broken up into their <i>user</i> and <i>@domain</i> 156 constituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and 157 <i>foo</i>. 158 159 Patterns are applied in the order as specified in the ta- 160 ble, until a pattern is found that matches the search 161 string. 162 163 Results are the same as with indexed file lookups, with 164 the additional feature that parenthesized substrings from 165 the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on. 166 167<b>TCP-BASED TABLES</b> 168 This section describes how the table lookups change when 169 lookups are directed to a TCP-based server. For a descrip- 170 tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a> 171 <a href="tcp_table.5.html"><b>ble</b>(5)</a>. This feature is not available up to and including 172 Postfix version 2.4. 173 174 Each lookup operation uses the entire address once. Thus, 175 <i>user@domain</i> mail addresses are not broken up into their 176 <i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i> broken 177 up into <i>user</i> and <i>foo</i>. 178 179 Results are the same as with indexed file lookups. 180 181<b>BUGS</b> 182 The table format does not understand quoting conventions. 183 184<b>CONFIGURATION PARAMETERS</b> 185 The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant. 186 The text below provides only a parameter summary. See 187 <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples. 188 189 <b><a href="postconf.5.html#canonical_classes">canonical_classes</a></b> 190 What addresses are subject to canonical address 191 mapping. 192 193 <b><a href="postconf.5.html#canonical_maps">canonical_maps</a></b> 194 List of canonical mapping tables. 195 196 <b><a href="postconf.5.html#recipient_canonical_maps">recipient_canonical_maps</a></b> 197 Address mapping lookup table for envelope and 198 header recipient addresses. 199 200 <b><a href="postconf.5.html#sender_canonical_maps">sender_canonical_maps</a></b> 201 Address mapping lookup table for envelope and 202 header sender addresses. 203 204 <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> 205 A list of address rewriting or forwarding mecha- 206 nisms that propagate an address extension from the 207 original address to the result. Specify zero or 208 more of <b>canonical</b>, <b>virtual</b>, <b>alias</b>, <b>forward</b>, 209 <b>include</b>, or <b>generic</b>. 210 211 Other parameters of interest: 212 213 <b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b> 214 The network interface addresses that this system 215 receives mail on. You need to stop and start Post- 216 fix when this parameter changes. 217 218 <b><a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a></b> 219 Rewrite message header addresses in mail from these 220 clients and update incomplete addresses with the 221 domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or $<a href="postconf.5.html#mydomain">mydomain</a>; either don't 222 rewrite message headers from other clients at all, 223 or rewrite message headers and update incomplete 224 addresses with the domain specified in the 225 <a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a> parameter. 226 227 <b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b> 228 Other interfaces that this machine receives mail on 229 by way of a proxy agent or network address transla- 230 tor. 231 232 <b><a href="postconf.5.html#masquerade_classes">masquerade_classes</a></b> 233 List of address classes subject to masquerading: 234 zero or more of <b>envelope_sender</b>, <b>envelope_recipi-</b> 235 <b>ent</b>, <b>header_sender</b>, <b>header_recipient</b>. 236 237 <b><a href="postconf.5.html#masquerade_domains">masquerade_domains</a></b> 238 List of domains that hide their subdomain struc- 239 ture. 240 241 <b><a href="postconf.5.html#masquerade_exceptions">masquerade_exceptions</a></b> 242 List of user names that are not subject to address 243 masquerading. 244 245 <b><a href="postconf.5.html#mydestination">mydestination</a></b> 246 List of domains that this mail system considers 247 local. 248 249 <b><a href="postconf.5.html#myorigin">myorigin</a></b> 250 The domain that is appended to locally-posted mail. 251 252 <b><a href="postconf.5.html#owner_request_special">owner_request_special</a></b> 253 Give special treatment to <b>owner-</b><i>xxx</i> and <i>xxx</i><b>-request</b> 254 addresses. 255 256 <b><a href="postconf.5.html#remote_header_rewrite_domain">remote_header_rewrite_domain</a></b> 257 Don't rewrite message headers from remote clients 258 at all when this parameter is empty; otherwise, re- 259 write message headers and append the specified 260 domain name to incomplete addresses. 261 262<b>SEE ALSO</b> 263 <a href="cleanup.8.html">cleanup(8)</a>, canonicalize and enqueue mail 264 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 265 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 266 <a href="virtual.5.html">virtual(5)</a>, virtual aliasing 267 268<b>README FILES</b> 269 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 270 <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a>, address rewriting guide 271 272<b>LICENSE</b> 273 The Secure Mailer license must be distributed with this 274 software. 275 276<b>AUTHOR(S)</b> 277 Wietse Venema 278 IBM T.J. Watson Research 279 P.O. Box 704 280 Yorktown Heights, NY 10598, USA 281 282 CANONICAL(5) 283</pre> </body> </html> 284