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 - virtual(5) </title> 7 </head> <body> <pre> 8 VIRTUAL(5) VIRTUAL(5) 9 10 <b><a name="name">NAME</a></b> 11 virtual - Postfix virtual alias table format 12 13 <b><a name="synopsis">SYNOPSIS</a></b> 14 <b>postmap /etc/postfix/virtual</b> 15 16 <b>postmap -q "</b><i>string</i><b>" /etc/postfix/virtual</b> 17 18 <b>postmap -q - /etc/postfix/virtual</b> <<i>inputfile</i> 19 20 <b><a name="description">DESCRIPTION</a></b> 21 The optional <a href="virtual.5.html"><b>virtual</b>(5)</a> alias table (<a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a>) applies to all 22 recipients: <a href="local.8.html">local(8)</a>, virtual, and remote. This feature is implemented 23 in the Postfix <a href="cleanup.8.html"><b>cleanup</b>(8)</a> daemon before mail is queued. These tables 24 are often queried with a full email address (including domain). 25 26 This is unlike the <a href="aliases.5.html"><b>aliases</b>(5)</a> table (<a href="postconf.5.html#alias_maps">alias_maps</a>) which applies only to 27 <a href="local.8.html"><b>local</b>(8)</a> recipients. That table is only queried with the email address 28 localpart (no domain). 29 30 Virtual aliasing is recursive; to terminate recursion for a specific 31 address, alias that address to itself. 32 33 The main applications of <a href="ADDRESS_REWRITING_README.html#virtual">virtual aliasing</a> are: 34 35 <b>o</b> To redirect mail for one address to one or more addresses. 36 37 <b>o</b> To implement virtual alias domains where all addresses are 38 aliased to addresses in other domains. 39 40 Virtual alias domains are not to be confused with the virtual 41 mailbox domains that are implemented with the Postfix <a href="virtual.8.html"><b>virtual</b>(8)</a> 42 mail delivery agent. With <a href="ADDRESS_CLASS_README.html#virtual_mailbox_class">virtual mailbox domains</a>, each recipi- 43 ent address can have its own mailbox. 44 45 Virtual aliasing is applied only to recipient envelope addresses, and 46 does not affect message headers. Use <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping to rewrite 47 header and envelope addresses in general. 48 49 Normally, the <a href="virtual.5.html"><b>virtual</b>(5)</a> alias table is specified as a text file that 50 serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command to create an indexed file for 51 fast lookup. 52 53 Execute the command "<b>postmap /etc/postfix/virtual</b>" to rebuild a 54 default-type indexed file after changing the text file, or execute 55 "<b>postmap</b> <i>type</i><b>:/etc/postfix/virtual</b>" to specify an explicit type. 56 57 The default indexed file type is configured with the <a href="postconf.5.html#default_database_type">default_data</a>- 58 <a href="postconf.5.html#default_database_type">base_type</a> parameter. Depending on the platform this may be one of 59 <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 ':'). 60 61 When the table is provided via other means such as NIS, LDAP or SQL, 62 the same lookups are done as for ordinary indexed files. Managing such 63 databases is outside the scope of Postfix. 64 65 Alternatively, the table can be provided as a regular-expression map 66 where patterns are given as regular expressions, or lookups can be 67 directed to a TCP-based server. In those case, the lookups are done in 68 a slightly different way as described below under "REGULAR EXPRESSION 69 TABLES" or "TCP-BASED TABLES". 70 71 <b><a name="case_folding">CASE FOLDING</a></b> 72 The search string is folded to lowercase before database lookup. As of 73 Postfix 2.3, the search string is not case folded with database types 74 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 75 lower case. 76 77 <b><a name="table_format">TABLE FORMAT</a></b> 78 The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows: 79 80 <i>pattern address, address, ...</i> 81 When <i>pattern</i> matches a mail address, replace it by the corre- 82 sponding <i>address</i>. 83 84 blank lines and comments 85 Empty lines and whitespace-only lines are ignored, as are lines 86 whose first non-whitespace character is a `#'. 87 88 multi-line text 89 A logical line starts with non-whitespace text. A line that 90 starts with whitespace continues a logical line. 91 92 <b><a name="table_search_order">TABLE SEARCH ORDER</a></b> 93 With lookups from indexed files such as DB or DBM, or from networked 94 tables such as NIS, LDAP or SQL, each <i>user</i>@<i>domain</i> query produces a 95 sequence of query patterns as described below. 96 97 Each query pattern is sent to each specified lookup table before trying 98 the next query pattern, until a match is found. 99 100 <i>user</i>@<i>domain address, address, ...</i> 101 Redirect mail for <i>user</i>@<i>domain</i> to <i>address</i>. This form has the 102 highest precedence. 103 104 <i>user address, address, ...</i> 105 Redirect mail for <i>user</i>@<i>site</i> to <i>address</i> when <i>site</i> is equal to 106 $<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>, or when it is 107 listed in $<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>. 108 109 This functionality overlaps with the functionality of the local 110 <i>aliases</i>(5) database. The difference is that <a href="virtual.5.html"><b>virtual</b>(5)</a> mapping 111 can be applied to non-local addresses. 112 113 @<i>domain address, address, ...</i> 114 Redirect mail for other users in <i>domain</i> to <i>address</i>. This form 115 has the lowest precedence. 116 117 Note: @<i>domain</i> is a wild-card. With this form, the Postfix SMTP 118 server accepts mail for any recipient in <i>domain</i>, regardless of 119 whether that recipient exists. This may turn your mail system 120 into a backscatter source: Postfix first accepts mail for 121 non-existent recipients and then tries to return that mail as 122 "undeliverable" to the often forged sender address. 123 124 To avoid backscatter with mail for a wild-card domain, replace 125 the wild-card mapping with explicit 1:1 mappings, or add a 126 <a href="postconf.5.html#reject_unverified_recipient">reject_unverified_recipient</a> restriction for that domain: 127 128 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = 129 ... 130 <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> 131 <a href="postconf.5.html#check_recipient_access">check_recipient_access</a> 132 <a href="DATABASE_README.html#types">inline</a>:{example.com=<a href="postconf.5.html#reject_unverified_recipient">reject_unverified_recipient</a>} 133 <a href="postconf.5.html#unverified_recipient_reject_code">unverified_recipient_reject_code</a> = 550 134 135 In the above example, Postfix may contact a remote server if the 136 recipient is aliased to a remote address. 137 138 <b><a name="result_address_rewriting">RESULT ADDRESS REWRITING</a></b> 139 The lookup result is subject to address rewriting: 140 141 <b>o</b> When the result has the form @<i>otherdomain</i>, the result becomes 142 the same <i>user</i> in <i>otherdomain</i>. This works only for the first 143 address in a multi-address lookup result. 144 145 <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 146 without "@domain". 147 148 <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 149 without ".domain". 150 151 <b><a name="address_extension">ADDRESS EXTENSION</a></b> 152 When a mail address localpart contains the optional recipient delimiter 153 (e.g., <i>user+foo</i>@<i>domain</i>), the lookup order becomes: <i>user+foo</i>@<i>domain</i>, 154 <i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and @<i>domain</i>. 155 156 The <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b> parameter controls whether an 157 unmatched address extension (<i>+foo</i>) is propagated to the result of a ta- 158 ble lookup. 159 160 <b><a name="virtual_alias_domains">VIRTUAL ALIAS DOMAINS</a></b> 161 Besides virtual aliases, the virtual alias table can also be used to 162 implement virtual alias domains. With a <a href="ADDRESS_CLASS_README.html#virtual_alias_class">virtual alias domain</a>, all 163 recipient addresses are aliased to addresses in other domains. 164 165 Virtual alias domains are not to be confused with the virtual mailbox 166 domains that are implemented with the Postfix <a href="virtual.8.html"><b>virtual</b>(8)</a> mail delivery 167 agent. With <a href="ADDRESS_CLASS_README.html#virtual_mailbox_class">virtual mailbox domains</a>, each recipient address can have 168 its own mailbox. 169 170 With a <a href="ADDRESS_CLASS_README.html#virtual_alias_class">virtual alias domain</a>, the virtual domain has its own user name 171 space. Local (i.e. non-virtual) usernames are not visible in a virtual 172 alias domain. In particular, local <a href="aliases.5.html"><b>aliases</b>(5)</a> and local mailing lists 173 are not visible as <i>localname (a] virtual-alias.domain</i>. 174 175 Support for a <a href="ADDRESS_CLASS_README.html#virtual_alias_class">virtual alias domain</a> looks like: 176 177 /etc/postfix/<a href="postconf.5.html">main.cf</a>: 178 <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/virtual 179 180 Note: some systems use <b>dbm</b> databases instead of <b>hash</b>. See the output 181 from "<b>postconf -m</b>" for available database types. 182 183 /etc/postfix/virtual: 184 <i>virtual-alias.domain anything</i> (right-hand content does not matter) 185 <i>postmaster (a] virtual-alias.domain postmaster</i> 186 <i>user1 (a] virtual-alias.domain address1</i> 187 <i>user2 (a] virtual-alias.domain address2, address3</i> 188 189 The <i>virtual-alias.domain anything</i> entry is required for a virtual alias 190 domain. <b>Without this entry, mail is rejected with "relay access</b> 191 <b>denied", or bounces with "mail loops back to myself".</b> 192 193 Do not specify <a href="ADDRESS_CLASS_README.html#virtual_alias_class">virtual alias domain</a> names in the <a href="postconf.5.html"><b>main.cf</a> <a href="postconf.5.html#mydestination">mydestination</a></b> 194 or <b><a href="postconf.5.html#relay_domains">relay_domains</a></b> configuration parameters. 195 196 With a <a href="ADDRESS_CLASS_README.html#virtual_alias_class">virtual alias domain</a>, the Postfix SMTP server accepts mail for 197 <i>known-user (a] virtual-alias.domain</i>, and rejects mail for <i>unknown-user</i>@<i>vir-</i> 198 <i>tual-alias.domain</i> as undeliverable. 199 200 Instead of specifying the virtual alias domain name via the <b><a href="postconf.5.html#virtual_alias_maps">vir</a>-</b> 201 <b><a href="postconf.5.html#virtual_alias_maps">tual_alias_maps</a></b> table, you may also specify it via the <a href="postconf.5.html"><b>main.cf</a> <a href="postconf.5.html#virtual_alias_domains">vir-</b> 202 <b>tual_alias_domains</a></b> configuration parameter. This latter parameter uses 203 the same syntax as the <a href="postconf.5.html"><b>main.cf</a> <a href="postconf.5.html#mydestination">mydestination</a></b> configuration parameter. 204 205 <b><a name="regular_expression_tables">REGULAR EXPRESSION TABLES</a></b> 206 This section describes how the table lookups change when the table is 207 given in the form of regular expressions. For a description of regular 208 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>. 209 210 Each pattern is a regular expression that is applied to the entire 211 address being looked up. Thus, <i>user@domain</i> mail addresses are not bro- 212 ken up into their <i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i> 213 broken up into <i>user</i> and <i>foo</i>. 214 215 Patterns are applied in the order as specified in the table, until a 216 pattern is found that matches the search string. 217 218 Results are the same as with indexed file lookups, with the additional 219 feature that parenthesized substrings from the pattern can be interpo- 220 lated as <b>$1</b>, <b>$2</b> and so on. 221 222 <b><a name="tcp-based_tables">TCP-BASED TABLES</a></b> 223 This section describes how the table lookups change when lookups are 224 directed to a TCP-based server. For a description of the TCP 225 client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>. This feature is 226 available in Postfix 2.5 and later. 227 228 Each lookup operation uses the entire address once. Thus, <i>user@domain</i> 229 mail addresses are not broken up into their <i>user</i> and <i>@domain</i> con- 230 stituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. 231 232 Results are the same as with indexed file lookups. 233 234 <b><a name="bugs">BUGS</a></b> 235 The table format does not understand quoting conventions. 236 237 <b><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></b> 238 The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant to this topic. 239 See the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file for syntax details and for default values. 240 Use the "<b>postfix reload</b>" command after a configuration change. 241 242 <b><a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> ($<a href="postconf.5.html#virtual_maps">virtual_maps</a>)</b> 243 Optional lookup tables that are often searched with a full email 244 address (including domain) and that apply to all recipients: 245 <a href="local.8.html"><b>local</b>(8)</a>, virtual, and remote; this is unlike <a href="postconf.5.html#alias_maps">alias_maps</a> that 246 are only searched with an email address localpart (no domain) 247 and that apply only to <a href="local.8.html"><b>local</b>(8)</a> recipients. 248 249 <b><a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a> ($<a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a>)</b> 250 Postfix is the final destination for the specified list of vir- 251 tual alias domains, that is, domains for which all addresses are 252 aliased to addresses in other local or remote domains. 253 254 <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a> (canonical, virtual)</b> 255 What address lookup tables copy an address extension from the 256 lookup key to the lookup result. 257 258 Other parameters of interest: 259 260 <b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b> 261 The local network interface addresses that this mail system 262 receives mail on. 263 264 <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> 265 The list of domains that are delivered via the $<a href="postconf.5.html#local_transport">local_transport</a> 266 mail delivery transport. 267 268 <b><a href="postconf.5.html#myorigin">myorigin</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b> 269 The domain name that locally-posted mail appears to come from, 270 and that locally posted mail is delivered to. 271 272 <b><a href="postconf.5.html#owner_request_special">owner_request_special</a> (yes)</b> 273 Enable special treatment for owner-<i>listname</i> entries in the 274 <a href="aliases.5.html"><b>aliases</b>(5)</a> file, and don't split owner-<i>listname</i> and <i>list-</i> 275 <i>name</i>-request address localparts when the <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> is 276 set to "-". 277 278 <b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b> 279 The remote network interface addresses that this mail system 280 receives mail on by way of a proxy or network address transla- 281 tion unit. 282 283 <b><a name="see_also">SEE ALSO</a></b> 284 <a href="cleanup.8.html">cleanup(8)</a>, canonicalize and enqueue mail 285 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 286 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 287 <a href="canonical.5.html">canonical(5)</a>, canonical address mapping 288 289 <b><a name="readme_files">README FILES</a></b> 290 <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a>, address rewriting guide 291 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 292 <a href="VIRTUAL_README.html">VIRTUAL_README</a>, domain hosting guide 293 294 <b><a name="license">LICENSE</a></b> 295 The Secure Mailer license must be distributed with this software. 296 297 <b>AUTHOR(S)</b> 298 Wietse Venema 299 IBM T.J. Watson Research 300 P.O. Box 704 301 Yorktown Heights, NY 10598, USA 302 303 Wietse Venema 304 Google, Inc. 305 111 8th Avenue 306 New York, NY 10011, USA 307 308 VIRTUAL(5) 309 </pre> </body> </html> 310
Indexes created Fri Sep 25 00:27:33 UTC 2026