xref: /netbsd-src/external/ibm-public/postfix/dist/proto/generic (revision 4a6720548cbf2e9325ed049c8a675ae86609f654)
1#++
2# NAME
3#	generic 5
4# SUMMARY
5#	Postfix generic table format
6# SYNOPSIS
7#	\fBpostmap /etc/postfix/generic\fR
8#
9#	\fBpostmap -q "\fIstring\fB" /etc/postfix/generic\fR
10#
11#	\fBpostmap -q - /etc/postfix/generic <\fIinputfile\fR
12# DESCRIPTION
13#	The optional \fBgeneric\fR(5) table specifies an address
14#	mapping that applies when mail is delivered. This is the
15#	opposite of \fBcanonical\fR(5) mapping, which applies when
16#	mail is received.
17#
18#	Typically, one would use the \fBgeneric\fR(5) table on a
19#	system that does not have a valid Internet domain name and
20#	that uses something like \fIlocaldomain.local\fR instead.
21#	The \fBgeneric\fR(5) table is then used by the \fBsmtp\fR(8)
22#	client to transform local mail addresses into valid Internet
23#	mail addresses when mail has to be sent across the Internet.
24#	See the EXAMPLE section at the end of this document.
25#
26#	The \fBgeneric\fR(5) mapping affects both message header
27#	addresses (i.e. addresses that appear inside messages) and
28#	message envelope addresses (for example, the addresses that
29#	are used in SMTP protocol commands).
30#
31#	Normally, the \fBgeneric\fR(5) table is specified as a
32#	text file that serves as input to the \fBpostmap\fR(1)
33#	command.  The result, an indexed file in \fBdbm\fR or
34#	\fBdb\fR format, is used for fast searching by the mail
35#	system. Execute the command "\fBpostmap /etc/postfix/generic\fR"
36#	to rebuild an indexed file after changing the corresponding
37#	text file.
38#
39#	When the table is provided via other means such as NIS, LDAP
40#	or SQL, the same lookups are done as for ordinary indexed files.
41#
42#	Alternatively, the table can be provided as a regular-expression
43#	map where patterns are given as regular expressions, or lookups
44#	can be directed to a TCP-based server. In those cases, the lookups
45#	are done in a slightly different way as described below under
46#	"REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES".
47# CASE FOLDING
48# .ad
49# .fi
50#	The search string is folded to lowercase before database
51#	lookup. As of Postfix 2.3, the search string is not case
52#	folded with database types such as regexp: or pcre: whose
53#	lookup fields can match both upper and lower case.
54# TABLE FORMAT
55# .ad
56# .fi
57#	The input format for the \fBpostmap\fR(1) command is as follows:
58# .IP "\fIpattern result\fR"
59#	When \fIpattern\fR matches a mail address, replace it by the
60#	corresponding \fIresult\fR.
61# .IP "blank lines and comments"
62#	Empty lines and whitespace-only lines are ignored, as
63#	are lines whose first non-whitespace character is a `#'.
64# .IP "multi-line text"
65#	A logical line starts with non-whitespace text. A line that
66#	starts with whitespace continues a logical line.
67# TABLE SEARCH ORDER
68# .ad
69# .fi
70#	With lookups from indexed files such as DB or DBM, or from networked
71#	tables such as NIS, LDAP or SQL, each \fIuser\fR@\fIdomain\fR
72#	query produces a sequence of query patterns as described below.
73#
74#	Each query pattern is sent to each specified lookup table
75#	before trying the next query pattern, until a match is
76#	found.
77# .IP "\fIuser\fR@\fIdomain address\fR"
78#	Replace \fIuser\fR@\fIdomain\fR by \fIaddress\fR. This form
79#	has the highest precedence.
80# .IP "\fIuser address\fR"
81#	Replace \fIuser\fR@\fIsite\fR by \fIaddress\fR when \fIsite\fR is
82#	equal to $\fBmyorigin\fR, when \fIsite\fR is listed in
83#	$\fBmydestination\fR, or when it is listed in $\fBinet_interfaces\fR
84#	or $\fBproxy_interfaces\fR.
85# .IP "@\fIdomain address\fR"
86#	Replace other addresses in \fIdomain\fR by \fIaddress\fR.
87#	This form has the lowest precedence.
88# RESULT ADDRESS REWRITING
89# .ad
90# .fi
91#	The lookup result is subject to address rewriting:
92# .IP \(bu
93#	When the result has the form @\fIotherdomain\fR, the
94#	result becomes the same \fIuser\fR in \fIotherdomain\fR.
95# .IP \(bu
96#	When "\fBappend_at_myorigin=yes\fR", append "\fB@$myorigin\fR"
97#	to addresses without "@domain".
98# .IP \(bu
99#	When "\fBappend_dot_mydomain=yes\fR", append
100#	"\fB.$mydomain\fR" to addresses without ".domain".
101# ADDRESS EXTENSION
102# .fi
103# .ad
104#	When a mail address localpart contains the optional recipient delimiter
105#	(e.g., \fIuser+foo\fR@\fIdomain\fR), the lookup order becomes:
106#	\fIuser+foo\fR@\fIdomain\fR, \fIuser\fR@\fIdomain\fR, \fIuser+foo\fR,
107#	\fIuser\fR, and @\fIdomain\fR.
108#
109#	The \fBpropagate_unmatched_extensions\fR parameter controls whether
110#	an unmatched address extension (\fI+foo\fR) is propagated to the
111#	result of table lookup.
112# REGULAR EXPRESSION TABLES
113# .ad
114# .fi
115#	This section describes how the table lookups change when the table
116#	is given in the form of regular expressions. For a description of
117#	regular expression lookup table syntax, see \fBregexp_table\fR(5)
118#	or \fBpcre_table\fR(5).
119#
120#	Each pattern is a regular expression that is applied to the entire
121#	address being looked up. Thus, \fIuser@domain\fR mail addresses are not
122#	broken up into their \fIuser\fR and \fI@domain\fR constituent parts,
123#	nor is \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR.
124#
125#	Patterns are applied in the order as specified in the table, until a
126#	pattern is found that matches the search string.
127#
128#	Results are the same as with indexed file lookups, with
129#	the additional feature that parenthesized substrings from the
130#	pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on.
131# TCP-BASED TABLES
132# .ad
133# .fi
134#	This section describes how the table lookups change when lookups
135#	are directed to a TCP-based server. For a description of the TCP
136#	client/server lookup protocol, see \fBtcp_table\fR(5).
137#	This feature is available in Postfix 2.5 and later.
138#
139#	Each lookup operation uses the entire address once.  Thus,
140#	\fIuser@domain\fR mail addresses are not broken up into their
141#	\fIuser\fR and \fI@domain\fR constituent parts, nor is
142#	\fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR.
143#
144#	Results are the same as with indexed file lookups.
145# EXAMPLE
146# .ad
147# .fi
148#	The following shows a generic mapping with an indexed file.
149#	When mail is sent to a remote host via SMTP, this replaces
150#	\fIhis@localdomain.local\fR by his ISP mail address, replaces
151#	\fIher@localdomain.local\fR by her ISP mail address, and
152#	replaces other local addresses by his ISP account, with
153#	an address extension of \fI+local\fR (this example assumes
154#	that the ISP supports "+" style address extensions).
155#
156# .na
157# .nf
158#	/etc/postfix/main.cf:
159#	    smtp_generic_maps = hash:/etc/postfix/generic
160#
161#	/etc/postfix/generic:
162#	    his@localdomain.local   hisaccount@hisisp.example
163#	    her@localdomain.local   heraccount@herisp.example
164#	    @localdomain.local      hisaccount+local@hisisp.example
165#
166# .ad
167# .fi
168#	Execute the command "\fBpostmap /etc/postfix/generic\fR"
169#	whenever the table is changed.  Instead of \fBhash\fR, some
170#	systems use \fBdbm\fR database files. To find out what
171#	tables your system supports use the command "\fBpostconf
172#	-m\fR".
173# BUGS
174#	The table format does not understand quoting conventions.
175# CONFIGURATION PARAMETERS
176# .ad
177# .fi
178#	The following \fBmain.cf\fR parameters are especially relevant.
179#	The text below provides only a parameter summary. See
180#	\fBpostconf\fR(5) for more details including examples.
181# .IP "\fBsmtp_generic_maps (empty)\fR"
182#	Optional lookup tables that perform address rewriting in the
183#	Postfix SMTP client, typically to transform a locally valid address into
184#	a globally valid address when sending mail across the Internet.
185# .IP "\fBpropagate_unmatched_extensions (canonical, virtual)\fR"
186#	What address lookup tables copy an address extension from the lookup
187#	key to the lookup result.
188# .PP
189#	Other parameters of interest:
190# .IP "\fBinet_interfaces (all)\fR"
191#	The network interface addresses that this mail system receives
192#	mail on.
193# .IP "\fBproxy_interfaces (empty)\fR"
194#	The network interface addresses that this mail system receives mail
195#	on by way of a proxy or network address translation unit.
196# .IP "\fBmydestination ($myhostname, localhost.$mydomain, localhost)\fR"
197#	The list of domains that are delivered via the $local_transport
198#	mail delivery transport.
199# .IP "\fBmyorigin ($myhostname)\fR"
200#	The domain name that locally-posted mail appears to come
201#	from, and that locally posted mail is delivered to.
202# .IP "\fBowner_request_special (yes)\fR"
203#	Enable special treatment for owner-\fIlistname\fR entries in the
204#	\fBaliases\fR(5) file, and don't split owner-\fIlistname\fR and
205#	\fIlistname\fR-request address localparts when the recipient_delimiter
206#	is set to "-".
207# SEE ALSO
208#	postmap(1), Postfix lookup table manager
209#	postconf(5), configuration parameters
210#	smtp(8), Postfix SMTP client
211# README FILES
212# .ad
213# .fi
214#	Use "\fBpostconf readme_directory\fR" or
215#	"\fBpostconf html_directory\fR" to locate this information.
216# .na
217# .nf
218#	ADDRESS_REWRITING_README, address rewriting guide
219#	DATABASE_README, Postfix lookup table overview
220#	STANDARD_CONFIGURATION_README, configuration examples
221# LICENSE
222# .ad
223# .fi
224#	The Secure Mailer license must be distributed with this software.
225# HISTORY
226#	A genericstable feature appears in the Sendmail MTA.
227#
228#	This feature is available in Postfix 2.2 and later.
229# AUTHOR(S)
230#	Wietse Venema
231#	IBM T.J. Watson Research
232#	P.O. Box 704
233#	Yorktown Heights, NY 10598, USA
234#
235#	Wietse Venema
236#	Google, Inc.
237#	111 8th Avenue
238#	New York, NY 10011, USA
239#--
240