summaryrefslogtreecommitdiffstats
path: root/proto/VERP_README.html
blob: 722b6f59ac4e7acd85d7e9bd0979c629d678cdcf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix VERP Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix VERP Howto</h1>

<hr>

<h2>Postfix VERP support</h2>

<p> Postfix versions 1.1 and later support variable envelope return
path addresses on request.  When VERP style delivery is requested,
each recipient of a message receives a customized copy of the
message, with his/her own recipient address encoded in the envelope
sender address.  </p>

<p> For example, when VERP style delivery is requested, Postfix
delivers mail from "<tt>owner-listname@origin</tt>" for a recipient
"<tt>user@domain</tt>", with a sender address that encodes the
recipient as follows: </p>

<blockquote>
<pre>
owner-listname+user=domain@origin
</pre>
</blockquote>

<p> Thus, undeliverable mail can reveal the undeliverable recipient
address without requiring the list owner to parse bounce messages.
</p>

<p> The VERP concept was popularized by the qmail MTA and by the ezmlm
mailing list manager.  See http://cr.yp.to/proto/verp.txt for the
ideas behind this concept. </p>

<p> Topics covered in this document: </p>

<ul>

<li> <a href="#config"> Postfix VERP configuration parameters </a>

<li> <a href="#majordomo"> Using VERP with majordomo etc. mailing lists </a>

<li> <a href="#smtp"> VERP support in the Postfix SMTP server</a>

<li> <a href="#sendmail"> VERP support in the Postfix sendmail command </a>

<li> <a href="#qmqp"> VERP support in the Postfix QMQP server </a>

</ul>

<h2> <a name="config"> Postfix VERP configuration parameters </a> </h2>

With Postfix, the whole process is controlled by four configuration
parameters.

<dl>

<dt> default_verp_delimiters (default value:  +=) 

    <dd> <p> What VERP delimiter characters Postfix uses when VERP
    style delivery is requested but no explicit delimiters are
    specified. </p>

<dt> verp_delimiter_filter (default: -+=) 

    <dd> <p> What characters Postfix accepts as VERP delimiter
    characters on the sendmail command line and in SMTP commands.
    Many characters must not be used as VERP delimiter characters,
    either because they already have a special meaning in email
    addresses (such as the @ or the %), because they are used as
    part of a username or domain name (such as alphanumerics), or
    because they are non-ASCII or control characters.  And who
    knows, some characters may tickle bugs in vulnerable software,
    and we would not want that to happen.  </p> </dd>

<dt> smtpd_authorized_verp_clients (default value: none) 

    <dd> <p> What SMTP clients are allowed to request VERP style
    delivery.  The Postfix QMQP server uses its own access control
    mechanism, and local submission (via /usr/sbin/sendmail etc.)
    is always authorized. To authorize a host, list its name, IP
    address, subnet (net/mask) or parent .domain. </p>

    <p> With Postfix versions 1.1 and 2.0, this parameter is called
    authorized_verp_clients (default: $mynetworks). </p> </dd>

<dt> disable_verp_bounces (default: no) 

    <dd> <p> Send one bounce report for multi-recipient VERP mail,
    instead of one bounce report per recipient. The default,
    one per recipient, is what ezmlm needs. </p> </dd>

</dl>

<h2> <a name="majordomo"> Using VERP with majordomo etc. mailing lists </a> </h2>

<p> In order to make VERP useful with majordomo etc. mailing lists,
you would configure the list manager to submit mail according
to one of the following two forms: </p>

<p> Postfix 2.3 and later: </p>

<blockquote>
<pre>
% sendmail -XV -f owner-listname other-arguments...

% sendmail -XV+= -f owner-listname other-arguments...
</pre>
</blockquote>

<p> Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax
for backwards compatibility, but will log a warning that reminds
you of the new syntax): </p>

<blockquote>
<pre>
% sendmail -V -f owner-listname other-arguments...

% sendmail -V+= -f owner-listname other-arguments...
</pre>
</blockquote>

<p> The first form uses the default main.cf VERP delimiter characters.
The second form allows you to explicitly specify the VERP delimiter
characters. The example shows the recommended values. </p>

<p> This text assumes that you have set up an owner-listname alias
that routes undeliverable mail to a real person: </p>

<blockquote>
<pre>
/etc/aliases:
    owner-listname: yourname+listname
</pre>
</blockquote>

<p> In order to process bounces we are going to make extensive use
of address extension tricks. </p>

<p> You need to tell Postfix that + is the separator between an
address and its optional address extension, that address extensions
are appended to .forward file names, and that address extensions
are to be discarded when doing alias expansions: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    recipient_delimiter = +
    forward_path = $home/.forward${recipient_delimiter}${extension},
        $home/.forward
    propagate_unmatched_extensions = canonical, virtual
</pre>
</blockquote>

<p> (the last two parameter settings are default settings). </p>

<p> You need to set up a file named .forward+listname with the
commands that process all the mail that is sent to the owner-listname
address: </p>

<blockquote>
<pre>
~/.forward+listname:
    "|/some/where/command ..."
</pre>
</blockquote>

<p> With this set up, undeliverable mail for user@domain will be returned
to the following address: </p>

<blockquote>
<pre>
owner-listname+user=domain@your.domain
</pre>
</blockquote>

<p> which is processed by the command in your .forward+listname file.
The message should contain, among others, a To: header with the
encapsulated recipient sender address: </p>

<blockquote>
<pre>
To: owner-listname+user=domain@your.domain
</pre>
</blockquote>

<p> It is left as an exercise for the reader to parse the To: header
line and to pull out the user=domain part from the recipient address.
</p>

<h2> <a name="smtp"> VERP support in the Postfix SMTP server </a> </h2>

<p> The Postfix SMTP server implements a command XVERP to enable
VERP style delivery. The syntax allows two forms: </p>

<blockquote>
<pre>
MAIL FROM:&lt;sender@domain&gt; XVERP

MAIL FROM:&lt;sender@domain&gt; XVERP=+=
</pre>
</blockquote>

<p> The first form uses the default main.cf VERP delimiters, the
second form overrides them explicitly. The values shown are the
recommended ones. </p>

<p> You can use the smtpd_command_filter feature to append XVERP
to SMTP commands from legacy software. This requires Postfix 2.7
or later. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    smtpd_command_filter = pcre:/etc/postfix/append_verp.pcre
    smtpd_authorized_verp_clients = $mynetworks

/etc/postfix/append_verp.pcre:
    /^(MAIL FROM:&lt;listname@example\.com&gt;.*)/ $1 XVERP
</pre>
</blockquote>

<h2> <a name="sendmail"> VERP support in the Postfix sendmail command </a> </h2>

<p> The Postfix sendmail command has a -V flag to request VERP style
delivery.  Specify one of the following two forms: </p>

<p> Postfix 2.3 and later:</p>
<blockquote>
<pre>
% sendmail -XV -f owner-listname ....

% sendmail -XV+= -f owner-listname ....
</pre>
</blockquote>

<p> Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax
for backwards compatibility, but will log a warning that reminds
you of the new syntax): </p>

<blockquote>
<pre>
% sendmail -V -f owner-listname ....

% sendmail -V+= -f owner-listname ....
</pre>
</blockquote>

<p> The first form uses the default main.cf VERP delimiters, the
second form overrides them explicitly. The values shown are the
recommended ones. </p>

<h2> <a name="qmqp"> VERP support in the Postfix QMQP server </a> </h2>

<p> When the Postfix QMQP server receives mail with an envelope
sender address of the form: </p>

<blockquote>
<pre>
listname-@your.domain-@[]
</pre>
</blockquote>

<p> Postfix generates sender addresses
"<tt>listname-user=domain@your.domain</tt>", using "-=" as the VERP
delimiters because qmail/ezmlm expect this.  </p>

<p> More generally, a sender address of "<tt>prefix@origin-@[]</tt>"
requests VERP style delivery with sender addresses of the form
"<tt>prefixuser=domain@origin</tt>". However, Postfix allows only
VERP delimiters that are specified with the verp_delimiter_filter
parameter. In particular, the "=" delimiter is required for qmail
compatibility (see the qmail addresses(5) manual page for details).

</body>

</html>