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