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