1VIRTUAL(5)                    File Formats Manual                   VIRTUAL(5)
2
3
4

NAME

6       virtual - Postfix virtual alias table format
7

SYNOPSIS

9       postmap /etc/postfix/virtual
10
11       postmap -q "string" /etc/postfix/virtual
12
13       postmap -q - /etc/postfix/virtual <inputfile
14

DESCRIPTION

16       The  optional  virtual(5)  alias table rewrites recipient addresses for
17       all local, all virtual, and all  remote  mail  destinations.   This  is
18       unlike  the  aliases(5) table which is used only for local(8) delivery.
19       Virtual aliasing is  recursive,  and  is  implemented  by  the  Postfix
20       cleanup(8) daemon before mail is queued.
21
22       The main applications of virtual aliasing are:
23
24       ·      To redirect mail for one address to one or more addresses.
25
26       ·      To  implement  virtual  alias  domains  where  all addresses are
27              aliased to addresses in other domains.
28
29              Virtual alias domains are not to be confused  with  the  virtual
30              mailbox domains that are implemented with the Postfix virtual(8)
31              mail delivery agent. With virtual mailbox domains, each  recipi‐
32              ent address can have its own mailbox.
33
34       Virtual  aliasing  is applied only to recipient envelope addresses, and
35       does not affect message headers.  Use canonical(5) mapping  to  rewrite
36       header and envelope addresses in general.
37
38       Normally,  the  virtual(5) alias table is specified as a text file that
39       serves as input to the postmap(1) command.  The result, an indexed file
40       in  dbm  or  db  format, is used for fast searching by the mail system.
41       Execute  the  command  "postmap  /etc/postfix/virtual"  to  rebuild  an
42       indexed file after changing the corresponding text file.
43
44       When  the  table  is provided via other means such as NIS, LDAP or SQL,
45       the same lookups are done as for ordinary indexed files.
46
47       Alternatively, the table can be provided as  a  regular-expression  map
48       where  patterns  are  given  as  regular expressions, or lookups can be
49       directed to TCP-based server. In those case, the lookups are done in  a
50       slightly  different  way  as  described below under "REGULAR EXPRESSION
51       TABLES" or "TCP-BASED TABLES".
52

CASE FOLDING

54       The search string is folded to lowercase before database lookup. As  of
55       Postfix  2.3,  the search string is not case folded with database types
56       such as regexp: or pcre: whose lookup fields can match both  upper  and
57       lower case.
58

TABLE FORMAT

60       The input format for the postmap(1) command is as follows:
61
62       pattern result
63              When  pattern  matches  a mail address, replace it by the corre‐
64              sponding result.
65
66       blank lines and comments
67              Empty lines and whitespace-only lines are ignored, as are  lines
68              whose first non-whitespace character is a `#'.
69
70       multi-line text
71              A  logical  line  starts  with  non-whitespace text. A line that
72              starts with whitespace continues a logical line.
73

TABLE SEARCH ORDER

75       With lookups from indexed files such as DB or DBM,  or  from  networked
76       tables  such  as  NIS,  LDAP  or SQL, each user@domain query produces a
77       sequence of query patterns as described below.
78
79       Each query pattern is sent to each specified lookup table before trying
80       the next query pattern, until a match is found.
81
82       user@domain address, address, ...
83              Redirect  mail  for  user@domain  to address.  This form has the
84              highest precedence.
85
86       user address, address, ...
87              Redirect mail for user@site to address when  site  is  equal  to
88              $myorigin,  when site is listed in $mydestination, or when it is
89              listed in $inet_interfaces or $proxy_interfaces.
90
91              This functionality overlaps  with  functionality  of  the  local
92              aliases(5)  database.  The difference is that virtual(5) mapping
93              can be applied to non-local addresses.
94
95       @domain address, address, ...
96              Redirect mail for other users in domain to address.   This  form
97              has the lowest precedence.
98
99              Note:  @domain  is a wild-card. With this form, the Postfix SMTP
100              server accepts mail for any recipient in domain,  regardless  of
101              whether  that  recipient exists.  This may turn your mail system
102              into a backscatter source: Postfix first accepts mail  for  non-
103              existent recipients and then tries to return that mail as "unde‐
104              liverable" to the often forged sender address.
105

RESULT ADDRESS REWRITING

107       The lookup result is subject to address rewriting:
108
109       ·      When the result has the form @otherdomain,  the  result  becomes
110              the  same  user  in  otherdomain.  This works only for the first
111              address in a multi-address lookup result.
112
113       ·      When "append_at_myorigin=yes", append "@$myorigin" to  addresses
114              without "@domain".
115
116       ·      When "append_dot_mydomain=yes", append ".$mydomain" to addresses
117              without ".domain".
118

ADDRESS EXTENSION

120       When a mail address localpart contains the optional recipient delimiter
121       (e.g.,  user+foo@domain),  the  lookup  order becomes: user+foo@domain,
122       user@domain, user+foo, user, and @domain.
123
124       The  propagate_unmatched_extensions  parameter  controls   whether   an
125       unmatched address extension (+foo) is propagated to the result of table
126       lookup.
127

VIRTUAL ALIAS DOMAINS

129       Besides virtual aliases, the virtual alias table can also  be  used  to
130       implement  virtual  alias  domains.  With  a  virtual alias domain, all
131       recipient addresses are aliased to addresses in other domains.
132
133       Virtual alias domains are not to be confused with the  virtual  mailbox
134       domains  that are implemented with the Postfix virtual(8) mail delivery
135       agent. With virtual mailbox domains, each recipient  address  can  have
136       its own mailbox.
137
138       With  a  virtual alias domain, the virtual domain has its own user name
139       space. Local (i.e. non-virtual) usernames are not visible in a  virtual
140       alias  domain.  In particular, local aliases(5) and local mailing lists
141       are not visible as localname@virtual-alias.domain.
142
143       Support for a virtual alias domain looks like:
144
145       /etc/postfix/main.cf:
146           virtual_alias_maps = hash:/etc/postfix/virtual
147
148       Note: some systems use dbm databases instead of hash.  See  the  output
149       from "postconf -m" for available database types.
150
151       /etc/postfix/virtual:
152           virtual-alias.domain     anything (right-hand content does not matter)
153           postmaster@virtual-alias.domain  postmaster
154           user1@virtual-alias.domain       address1
155           user2@virtual-alias.domain       address2, address3
156
157       The virtual-alias.domain anything entry is required for a virtual alias
158       domain. Without  this  entry,  mail  is  rejected  with  "relay  access
159       denied", or bounces with "mail loops back to myself".
160
161       Do  not specify virtual alias domain names in the main.cf mydestination
162       or relay_domains configuration parameters.
163
164       With a virtual alias domain, the Postfix SMTP server accepts  mail  for
165       known-user@virtual-alias.domain, and rejects mail for unknown-user@vir‐
166       tual-alias.domain as undeliverable.
167
168       Instead of specifying the  virtual  alias  domain  name  via  the  vir‐
169       tual_alias_maps  table,  you  may  also specify it via the main.cf vir‐
170       tual_alias_domains configuration parameter.  This latter parameter uses
171       the same syntax as the main.cf mydestination configuration parameter.
172

REGULAR EXPRESSION TABLES

174       This  section  describes how the table lookups change when the table is
175       given in the form of regular expressions. For a description of  regular
176       expression lookup table syntax, see regexp_table(5) or pcre_table(5).
177
178       Each  pattern  is  a  regular  expression that is applied to the entire
179       address being looked up. Thus, user@domain mail addresses are not  bro‐
180       ken  up  into their user and @domain constituent parts, nor is user+foo
181       broken up into user and foo.
182
183       Patterns are applied in the order as specified in the  table,  until  a
184       pattern is found that matches the search string.
185
186       Results  are the same as with indexed file lookups, with the additional
187       feature that parenthesized substrings from the pattern can be  interpo‐
188       lated as $1, $2 and so on.
189

TCP-BASED TABLES

191       This  section  describes  how the table lookups change when lookups are
192       directed  to  a  TCP-based  server.  For  a  description  of  the   TCP
193       client/server  lookup  protocol, see tcp_table(5).  This feature is not
194       available up to and including Postfix version 2.4.
195
196       Each lookup operation uses the entire address once.  Thus,  user@domain
197       mail  addresses  are  not  broken  up  into their user and @domain con‐
198       stituent parts, nor is user+foo broken up into user and foo.
199
200       Results are the same as with indexed file lookups.
201

BUGS

203       The table format does not understand quoting conventions.
204

CONFIGURATION PARAMETERS

206       The following main.cf parameters are especially relevant to this topic.
207       See the Postfix main.cf file for syntax details and for default values.
208       Use the "postfix reload" command after a configuration change.
209
210       virtual_alias_maps
211              List of virtual aliasing tables.
212
213       virtual_alias_domains
214              List of virtual alias domains. This uses the same syntax as  the
215              mydestination parameter.
216
217       propagate_unmatched_extensions
218              A list of address rewriting or forwarding mechanisms that propa‐
219              gate an address extension  from  the  original  address  to  the
220              result.  Specify zero or more of canonical, virtual, alias, for‐
221              ward, include, or generic.
222
223       Other parameters of interest:
224
225       inet_interfaces
226              The network interface addresses that this system  receives  mail
227              on.   You  need  to  stop  and start Postfix when this parameter
228              changes.
229
230       mydestination
231              List of domains that this mail system considers local.
232
233       myorigin
234              The domain that is appended to any address that does not have  a
235              domain.
236
237       owner_request_special
238              Give special treatment to owner-xxx and xxx-request addresses.
239
240       proxy_interfaces
241              Other  interfaces that this machine receives mail on by way of a
242              proxy agent or network address translator.
243

SEE ALSO

245       cleanup(8), canonicalize and enqueue mail
246       postmap(1), Postfix lookup table manager
247       postconf(5), configuration parameters
248       canonical(5), canonical address mapping
249

README FILES

251       Use "postconf readme_directory" or "postconf html_directory" to  locate
252       this information.
253       ADDRESS_REWRITING_README, address rewriting guide
254       DATABASE_README, Postfix lookup table overview
255       VIRTUAL_README, domain hosting guide
256

LICENSE

258       The Secure Mailer license must be distributed with this software.
259

AUTHOR(S)

261       Wietse Venema
262       IBM T.J. Watson Research
263       P.O. Box 704
264       Yorktown Heights, NY 10598, USA
265
266
267
268                                                                    VIRTUAL(5)
Impressum