postfix-master/VERP_README.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5
   6 <head>
   7
   8 <title>Postfix VERP Howto</title>
   9
  10 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  11
  12 </head>
  13
  14 <body>
  15
  16 <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix VERP Howto</h1>
  17
  18 <hr>
  19
  20 <h2>Postfix VERP support</h2>
  21
  22 <p> Postfix versions 1.1 and later support variable envelope return
  23 path addresses on request.  When VERP style delivery is requested,
  24 each recipient of a message receives a customized copy of the
  25 message, with his/her own recipient address encoded in the envelope
  26 sender address.  </p>
  27
  28 <p> For example, when VERP style delivery is requested, Postfix
  29 delivers mail from "<tt>owner-listname@origin</tt>" for a recipient
  30 "<tt>user@domain</tt>", with a sender address that encodes the
  31 recipient as follows: </p>
  32
  33 <blockquote>
  34 <pre>
  35 owner-listname+user=domain@origin
  36 </pre>
  37 </blockquote>
  38
  39 <p> Thus, undeliverable mail can reveal the undeliverable recipient
  40 address without requiring the list owner to parse bounce messages.
  41 </p>
  42
  43 <p> The VERP concept was popularized by the qmail MTA and by the ezmlm
  44 mailing list manager.  See <a href="http://cr.yp.to/proto/verp.txt">http://cr.yp.to/proto/verp.txt</a> for the
  45 ideas behind this concept. </p>
  46
  47 <p> Topics covered in this document: </p>
  48
  49 <ul>
  50
  51 <li> <a href="#config"> Postfix VERP configuration parameters </a>
  52
  53 <li> <a href="#majordomo"> Using VERP with majordomo etc. mailing lists </a>
  54
  55 <li> <a href="#smtp"> VERP support in the Postfix SMTP server</a>
  56
  57 <li> <a href="#sendmail"> VERP support in the Postfix sendmail command </a>
  58
  59 <li> <a href="#qmqp"> VERP support in the Postfix QMQP server </a>
  60
  61 </ul>
  62
  63 <h2> <a name="config"> Postfix VERP configuration parameters </a> </h2>
  64
  65 With Postfix, the whole process is controlled by four configuration
  66 parameters.
  67
  68 <dl>
  69
  70 <dt> <a href="postconf.5.html#default_verp_delimiters">default_verp_delimiters</a> (default value:  +=)
  71
  72     <dd> <p> What VERP delimiter characters Postfix uses when VERP
  73     style delivery is requested but no explicit delimiters are
  74     specified. </p>
  75
  76 <dt> <a href="postconf.5.html#verp_delimiter_filter">verp_delimiter_filter</a> (default: -+=)
  77
  78     <dd> <p> What characters Postfix accepts as VERP delimiter
  79     characters on the sendmail command line and in SMTP commands.
  80     Many characters must not be used as VERP delimiter characters,
  81     either because they already have a special meaning in email
  82     addresses (such as the @ or the %), because they are used as
  83     part of a username or domain name (such as alphanumerics), or
  84     because they are non-ASCII or control characters.  And who
  85     knows, some characters may tickle bugs in vulnerable software,
  86     and we would not want that to happen.  </p> </dd>
  87
  88 <dt> <a href="postconf.5.html#smtpd_authorized_verp_clients">smtpd_authorized_verp_clients</a> (default value: none)
  89
  90     <dd> <p> What SMTP clients are allowed to request VERP style
  91     delivery.  The Postfix QMQP server uses its own access control
  92     mechanism, and local submission (via /usr/sbin/sendmail etc.)
  93     is always authorized. To authorize a host, list its name, IP
  94     address, subnet (net/mask) or parent .domain. </p>
  95
  96     <p> With Postfix versions 1.1 and 2.0, this parameter is called
  97     <a href="postconf.5.html#authorized_verp_clients">authorized_verp_clients</a> (default: $<a href="postconf.5.html#mynetworks">mynetworks</a>). </p> </dd>
  98
  99 <dt> <a href="postconf.5.html#disable_verp_bounces">disable_verp_bounces</a> (default: no)
 100
 101     <dd> <p> if Postfix sends one bounce report for multi-recipient
 102     VERP mail, or one bounce report per recipient. The default,
 103     one per recipient, is what ezmlm needs. </p> </dd>
 104
 105 </dl>
 106
 107 <h2> <a name="majordomo"> Using VERP with majordomo etc. mailing lists </a> </h2>
 108
 109 <p> In order to make VERP useful with majordomo etc. mailing lists,
 110 you would configure the list manager to submit mail according
 111 to one of the following two forms: </p>
 112
 113 <p> Postfix 2.3 and later: </p>
 114
 115 <blockquote>
 116 <pre>
 117 % sendmail -XV -f owner-listname other-arguments...
 118
 119 % sendmail -XV+= -f owner-listname other-arguments...
 120 </pre>
 121 </blockquote>
 122
 123 <p> Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax
 124 for backwards compatibility, but will log a warning that reminds
 125 you of the new syntax): </p>
 126
 127 <blockquote>
 128 <pre>
 129 % sendmail -V -f owner-listname other-arguments...
 130
 131 % sendmail -V+= -f owner-listname other-arguments...
 132 </pre>
 133 </blockquote>
 134
 135 <p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiter characters.
 136 The second form allows you to explicitly specify the VERP delimiter
 137 characters. The example shows the recommended values. </p>
 138
 139 <p> This text assumes that you have set up an owner-listname alias
 140 that routes undeliverable mail to a real person: </p>
 141
 142 <blockquote>
 143 <pre>
 144 /etc/aliases:
 145     owner-listname: yourname+listname
 146 </pre>
 147 </blockquote>
 148
 149 <p> In order to process bounces we are going to make extensive use
 150 of address extension tricks. </p>
 151
 152 <p> You need to tell Postfix that + is the separator between an
 153 address and its optional address extension, that address extensions
 154 are appended to .forward file names, and that address extensions
 155 are to be discarded when doing alias expansions: </p>
 156
 157 <blockquote>
 158 <pre>
 159 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 160     <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> = +
 161     <a href="postconf.5.html#forward_path">forward_path</a> = $home/.forward${<a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a>}${extension},
 162         $home/.forward
 163     <a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a> = canonical, virtual
 164 </pre>
 165 </blockquote>
 166
 167 <p> (the last two parameter settings are default settings). </p>
 168
 169 <p> You need to set up a file named .forward+listname with the
 170 commands that process all the mail that is sent to the owner-listname
 171 address: </p>
 172
 173 <blockquote>
 174 <pre>
 175 ~/.forward+listname:
 176     "|/some/where/command ..."
 177 </pre>
 178 </blockquote>
 179
 180 <p> With this set up, undeliverable mail for user@domain will be returned
 181 to the following address: </p>
 182
 183 <blockquote>
 184 <pre>
 185 owner-listname+user=domain@your.domain
 186 </pre>
 187 </blockquote>
 188
 189 <p> which is processed by the command in your .forward+listname file.
 190 The message should contain, among others, a To: header with the
 191 encapsulated recipient sender address: </p>
 192
 193 <blockquote>
 194 <pre>
 195 To: owner-listname+user=domain@your.domain
 196 </pre>
 197 </blockquote>
 198
 199 <p> It is left as an exercise for the reader to parse the To: header
 200 line and to pull out the user=domain part from the recipient address.
 201 </p>
 202
 203 <h2> <a name="smtp"> VERP support in the Postfix SMTP server </a> </h2>
 204
 205 <p> The Postfix SMTP server implements a command XVERP to enable
 206 VERP style delivery. The syntax allows two forms: </p>
 207
 208 <blockquote>
 209 <pre>
 210 MAIL FROM:&lt;sender@domain&gt; XVERP
 211
 212 MAIL FROM:&lt;sender@domain&gt; XVERP=+=
 213 </pre>
 214 </blockquote>
 215
 216 <p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiters, the
 217 second form overrides them explicitly. The values shown are the
 218 recommended ones. </p>
 219
 220 <h2> <a name="sendmail"> VERP support in the Postfix sendmail command </a> </h2>
 221
 222 <p> The Postfix sendmail command has a -V flag to request VERP style
 223 delivery.  Specify one of the following two forms: </p>
 224
 225 <p> Postfix 2.3 and later:</p>
 226 <blockquote>
 227 <pre>
 228 % sendmail -XV -f owner-listname ....
 229
 230 % sendmail -XV+= -f owner-listname ....
 231 </pre>
 232 </blockquote>
 233
 234 <p> Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax
 235 for backwards compatibility, but will log a warning that reminds
 236 you of the new syntax): </p>
 237
 238 <blockquote>
 239 <pre>
 240 % sendmail -V -f owner-listname ....
 241
 242 % sendmail -V+= -f owner-listname ....
 243 </pre>
 244 </blockquote>
 245
 246 <p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiters, the
 247 second form overrides them explicitly. The values shown are the
 248 recommended ones. </p>
 249
 250 <h2> <a name="qmqp"> VERP support in the Postfix QMQP server </a> </h2>
 251
 252 <p> When the Postfix QMQP server receives mail with an envelope
 253 sender address of the form: </p>
 254
 255 <blockquote>
 256 <pre>
 257 listname-@your.domain-@[]
 258 </pre>
 259 </blockquote>
 260
 261 <p> Postfix generates sender addresses
 262 "<tt>listname-user=domain@your.domain</tt>", using "-=" as the VERP
 263 delimiters because qmail/ezmlm expect this.  </p>
 264
 265 <p> More generally, a sender address of "<tt>prefix@origin-@[]</tt>"
 266 requests VERP style delivery with sender addresses of the form
 267 "<tt>prefixuser=domain@origin</tt>". However, Postfix allows only
 268 VERP delimiters that are specified with the <a href="postconf.5.html#verp_delimiter_filter">verp_delimiter_filter</a>
 269 parameter. In particular, the "=" delimiter is required for qmail
 270 compatibility (see the qmail addresses(5) manual page for details).
 271
 272 </body>
 273
 274 </html>