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, patterns are tried in the order as
77       listed below:
78
79       user@domain address, address, ...
80              Redirect mail for user@domain to address.   This  form  has  the
81              highest precedence.
82
83       user address, address, ...
84              Redirect  mail  for  user@site  to address when site is equal to
85              $myorigin, when site is listed in $mydestination, or when it  is
86              listed in $inet_interfaces or $proxy_interfaces.
87
88              This  functionality  overlaps  with  functionality  of the local
89              aliases(5) database. The difference is that  virtual(5)  mapping
90              can be applied to non-local addresses.
91
92       @domain address, address, ...
93              Redirect  mail  for other users in domain to address.  This form
94              has the lowest precedence.
95
96              Note: @domain is a wild-card. With this form, the  Postfix  SMTP
97              server  accepts  mail for any recipient in domain, regardless of
98              whether that recipient exists.  This may turn your  mail  system
99              into  a  backscatter source: Postfix first accepts mail for non-
100              existent recipients and then tries to return that mail as "unde‐
101              liverable" to the often forged sender address.
102

RESULT ADDRESS REWRITING

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

ADDRESS EXTENSION

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

VIRTUAL ALIAS DOMAINS

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

REGULAR EXPRESSION TABLES

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

TCP-BASED TABLES

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

BUGS

200       The table format does not understand quoting conventions.
201

CONFIGURATION PARAMETERS

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

SEE ALSO

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

README FILES

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

LICENSE

255       The Secure Mailer license must be distributed with this software.
256

AUTHOR(S)

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