| blob | 8a2d28f607dbecab1be42a873e95ce13df07e4f3 |
1 #++
2 # NAME
3 # virtual 5
4 # SUMMARY
5 # Postfix virtual alias table format
6 # SYNOPSIS
7 # \fBpostmap /etc/postfix/virtual\fR
8 #
9 # \fBpostmap -q "\fIstring\fB" /etc/postfix/virtual\fR
10 #
11 # \fBpostmap -q - /etc/postfix/virtual <\fIinputfile\fR
12 # DESCRIPTION
13 # The optional \fBvirtual\fR(5) alias table rewrites recipient
14 # addresses for all local, all virtual, and all remote mail
15 # destinations.
16 # This is unlike the \fBaliases\fR(5) table which is used
17 # only for \fBlocal\fR(8) delivery. Virtual aliasing is
18 # recursive, and is implemented by the Postfix \fBcleanup\fR(8)
19 # daemon before mail is queued.
20 #
21 # The main applications of virtual aliasing are:
22 # .IP \(bu
23 # To redirect mail for one address to one or more addresses.
24 # .IP \(bu
25 # To implement virtual alias domains where all addresses are aliased
26 # to addresses in other domains.
27 # .sp
28 # Virtual alias domains are not to be confused with the virtual mailbox
29 # domains that are implemented with the Postfix \fBvirtual\fR(8) mail
30 # delivery agent. With virtual mailbox domains, each recipient address
31 # can have its own mailbox.
32 # .PP
33 # Virtual aliasing is applied only to recipient
34 # envelope addresses, and does not affect message headers.
35 # Use \fBcanonical\fR(5)
36 # mapping to rewrite header and envelope addresses in general.
37 #
38 # Normally, the \fBvirtual\fR(5) alias table is specified as a text file
39 # that serves as input to the \fBpostmap\fR(1) command.
40 # The result, an indexed file in \fBdbm\fR or \fBdb\fR format,
41 # is used for fast searching by the mail system. Execute the command
42 # "\fBpostmap /etc/postfix/virtual\fR" to rebuild an indexed
43 # file after changing the corresponding text file.
44 #
45 # When the table is provided via other means such as NIS, LDAP
46 # or SQL, the same lookups are done as for ordinary indexed files.
47 #
48 # Alternatively, the table can be provided as a regular-expression
49 # map where patterns are given as regular expressions, or lookups
50 # can be directed to TCP-based server. In those case, the lookups
51 # are done in a slightly different way as described below under
52 # "REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES".
53 # CASE FOLDING
54 # .ad
55 # .fi
56 # The search string is folded to lowercase before database
57 # lookup. As of Postfix 2.3, the search string is not case
58 # folded with database types such as regexp: or pcre: whose
59 # lookup fields can match both upper and lower case.
60 # TABLE FORMAT
61 # .ad
62 # .fi
63 # The input format for the \fBpostmap\fR(1) command is as follows:
64 # .IP "\fIpattern result\fR"
65 # When \fIpattern\fR matches a mail address, replace it by the
66 # corresponding \fIresult\fR.
67 # .IP "blank lines and comments"
68 # Empty lines and whitespace-only lines are ignored, as
69 # are lines whose first non-whitespace character is a `#'.
70 # .IP "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
74 # .ad
75 # .fi
76 # With lookups from indexed files such as DB or DBM, or from networked
77 # tables such as NIS, LDAP or SQL, patterns are tried in the order as
78 # listed below:
79 # .IP "\fIuser\fR@\fIdomain address, address, ...\fR"
80 # Redirect mail for \fIuser\fR@\fIdomain\fR to \fIaddress\fR.
81 # This form has the highest precedence.
82 # .IP "\fIuser address, address, ...\fR"
83 # Redirect mail for \fIuser\fR@\fIsite\fR to \fIaddress\fR when
84 # \fIsite\fR is equal to $\fBmyorigin\fR, when \fIsite\fR is listed in
85 # $\fBmydestination\fR, or when it is listed in $\fBinet_interfaces\fR
86 # or $\fBproxy_interfaces\fR.
87 # .sp
88 # This functionality overlaps with functionality of the local
89 # \fIaliases\fR(5) database. The difference is that \fBvirtual\fR(5)
90 # mapping can be applied to non-local addresses.
91 # .IP "@\fIdomain address, address, ...\fR"
92 # Redirect mail for other users in \fIdomain\fR to \fIaddress\fR.
93 # This form has the lowest precedence.
94 # .sp
95 # Note: @\fIdomain\fR is a wild-card. With this form, the
96 # Postfix SMTP server accepts
97 # mail for any recipient in \fIdomain\fR, regardless of whether
98 # that recipient exists. This may turn your mail system into
99 # a backscatter source: Postfix first accepts mail for
100 # non-existent recipients and then tries to return that mail
101 # as "undeliverable" to the often forged sender address.
102 # RESULT ADDRESS REWRITING
103 # .ad
104 # .fi
105 # The lookup result is subject to address rewriting:
106 # .IP \(bu
107 # When the result has the form @\fIotherdomain\fR, the
108 # result becomes the same \fIuser\fR in \fIotherdomain\fR.
109 # This works only for the first address in a multi-address
110 # lookup result.
111 # .IP \(bu
112 # When "\fBappend_at_myorigin=yes\fR", append "\fB@$myorigin\fR"
113 # to addresses without "@domain".
114 # .IP \(bu
115 # When "\fBappend_dot_mydomain=yes\fR", append
116 # "\fB.$mydomain\fR" to addresses without ".domain".
117 # ADDRESS EXTENSION
118 # .fi
119 # .ad
120 # When a mail address localpart contains the optional recipient delimiter
121 # (e.g., \fIuser+foo\fR@\fIdomain\fR), the lookup order becomes:
122 # \fIuser+foo\fR@\fIdomain\fR, \fIuser\fR@\fIdomain\fR, \fIuser+foo\fR,
123 # \fIuser\fR, and @\fIdomain\fR.
124 #
125 # The \fBpropagate_unmatched_extensions\fR parameter controls whether
126 # an unmatched address extension (\fI+foo\fR) is propagated to the
127 # result of table lookup.
128 # VIRTUAL ALIAS DOMAINS
129 # .ad
130 # .fi
131 # Besides virtual aliases, the virtual alias table can also be used
132 # to implement virtual alias domains. With a virtual alias domain, all
133 # recipient addresses are aliased to addresses in other domains.
134 #
135 # Virtual alias domains are not to be confused with the virtual mailbox
136 # domains that are implemented with the Postfix \fBvirtual\fR(8) mail
137 # delivery agent. With virtual mailbox domains, each recipient address
138 # can have its own mailbox.
139 #
140 # With a virtual alias domain, the virtual domain has its
141 # own user name space. Local (i.e. non-virtual) usernames are not
142 # visible in a virtual alias domain. In particular, local
143 # \fBaliases\fR(5) and local mailing lists are not visible as
144 # \fIlocalname@virtual-alias.domain\fR.
145 #
146 # Support for a virtual alias domain looks like:
147 #
148 # .nf
149 # /etc/postfix/main.cf:
150 # virtual_alias_maps = hash:/etc/postfix/virtual
151 # .fi
152 #
153 # Note: some systems use \fBdbm\fR databases instead of \fBhash\fR.
154 # See the output from "\fBpostconf -m\fR" for available database types.
155 #
156 # .nf
157 # /etc/postfix/virtual:
158 # \fIvirtual-alias.domain anything\fR (right-hand content does not matter)
159 # \fIpostmaster@virtual-alias.domain postmaster\fR
160 # \fIuser1@virtual-alias.domain address1\fR
161 # \fIuser2@virtual-alias.domain address2, address3\fR
162 # .fi
163 # .sp
164 # The \fIvirtual-alias.domain anything\fR entry is required for a
165 # virtual alias domain. \fBWithout this entry, mail is rejected
166 # with "relay access denied", or bounces with
167 # "mail loops back to myself".\fR
168 #
169 # Do not specify virtual alias domain names in the \fBmain.cf
170 # mydestination\fR or \fBrelay_domains\fR configuration parameters.
171 #
172 # With a virtual alias domain, the Postfix SMTP server
173 # accepts mail for \fIknown-user@virtual-alias.domain\fR, and rejects
174 # mail for \fIunknown-user\fR@\fIvirtual-alias.domain\fR as undeliverable.
175 #
176 # Instead of specifying the virtual alias domain name via
177 # the \fBvirtual_alias_maps\fR table, you may also specify it via
178 # the \fBmain.cf virtual_alias_domains\fR configuration parameter.
179 # This latter parameter uses the same syntax as the \fBmain.cf
180 # mydestination\fR configuration parameter.
181 # REGULAR EXPRESSION TABLES
182 # .ad
183 # .fi
184 # This section describes how the table lookups change when the table
185 # is given in the form of regular expressions. For a description of
186 # regular expression lookup table syntax, see \fBregexp_table\fR(5)
187 # or \fBpcre_table\fR(5).
188 #
189 # Each pattern is a regular expression that is applied to the entire
190 # address being looked up. Thus, \fIuser@domain\fR mail addresses are not
191 # broken up into their \fIuser\fR and \fI@domain\fR constituent parts,
192 # nor is \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR.
193 #
194 # Patterns are applied in the order as specified in the table, until a
195 # pattern is found that matches the search string.
196 #
197 # Results are the same as with indexed file lookups, with
198 # the additional feature that parenthesized substrings from the
199 # pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on.
200 # TCP-BASED TABLES
201 # .ad
202 # .fi
203 # This section describes how the table lookups change when lookups
204 # are directed to a TCP-based server. For a description of the TCP
205 # client/server lookup protocol, see \fBtcp_table\fR(5).
206 # This feature is not available up to and including Postfix version 2.4.
207 #
208 # Each lookup operation uses the entire address once. Thus,
209 # \fIuser@domain\fR mail addresses are not broken up into their
210 # \fIuser\fR and \fI@domain\fR constituent parts, nor is
211 # \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR.
212 #
213 # Results are the same as with indexed file lookups.
214 # BUGS
215 # The table format does not understand quoting conventions.
216 # CONFIGURATION PARAMETERS
217 # .ad
218 # .fi
219 # The following \fBmain.cf\fR parameters are especially relevant to
220 # this topic. See the Postfix \fBmain.cf\fR file for syntax details
221 # and for default values. Use the "\fBpostfix reload\fR" command after
222 # a configuration change.
223 # .IP \fBvirtual_alias_maps\fR
224 # List of virtual aliasing tables.
225 # .IP \fBvirtual_alias_domains\fR
226 # List of virtual alias domains. This uses the same syntax
227 # as the \fBmydestination\fR parameter.
228 # .IP \fBpropagate_unmatched_extensions\fR
229 # A list of address rewriting or forwarding mechanisms that propagate
230 # an address extension from the original address to the result.
231 # Specify zero or more of \fBcanonical\fR, \fBvirtual\fR, \fBalias\fR,
232 # \fBforward\fR, \fBinclude\fR, or \fBgeneric\fR.
233 # .PP
234 # Other parameters of interest:
235 # .IP \fBinet_interfaces\fR
236 # The network interface addresses that this system receives mail on.
237 # You need to stop and start Postfix when this parameter changes.
238 # .IP \fBmydestination\fR
239 # List of domains that this mail system considers local.
240 # .IP \fBmyorigin\fR
241 # The domain that is appended to any address that does not have a domain.
242 # .IP \fBowner_request_special\fR
243 # Give special treatment to \fBowner-\fIxxx\fR and \fIxxx\fB-request\fR
244 # addresses.
245 # .IP \fBproxy_interfaces\fR
246 # Other interfaces that this machine receives mail on by way of a
247 # proxy agent or network address translator.
248 # SEE ALSO
249 # cleanup(8), canonicalize and enqueue mail
250 # postmap(1), Postfix lookup table manager
251 # postconf(5), configuration parameters
252 # canonical(5), canonical address mapping
253 # README FILES
254 # .ad
255 # .fi
256 # Use "\fBpostconf readme_directory\fR" or
257 # "\fBpostconf html_directory\fR" to locate this information.
258 # .na
259 # .nf
260 # ADDRESS_REWRITING_README, address rewriting guide
261 # DATABASE_README, Postfix lookup table overview
262 # VIRTUAL_README, domain hosting guide
263 # LICENSE
264 # .ad
265 # .fi
266 # The Secure Mailer license must be distributed with this software.
267 # AUTHOR(S)
268 # Wietse Venema
269 # IBM T.J. Watson Research
270 # P.O. Box 704
271 # Yorktown Heights, NY 10598, USA
272 #--