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