postfix-master/ETRN_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 ETRN 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 ETRN Howto</h1>
  17
  18 <hr>
  19
  20 <h2>Purpose of the Postfix fast ETRN service</h2>
  21
  22 <p> The SMTP ETRN command was designed for sites that have intermittent
  23 Internet connectivity. With ETRN, a site can tell the mail server
  24 of its provider to "Please deliver all my mail now". The SMTP server
  25 searches the queue for mail to the customer, and delivers that mail
  26 <b>by connecting to the customer's SMTP server</b>. The mail is
  27 not delivered via the connection that was used for sending ETRN.
  28 </p>
  29
  30 <p> As of version 1.0, Postfix has a fast ETRN implementation that
  31 does not require Postfix to examine every queue file.  Instead,
  32 Postfix maintains a record of what queue files contain mail for
  33 destinations that are configured for ETRN service.  ETRN service
  34 is no longer available for domains that aren't configured for the
  35 service.  </p>
  36
  37 <p> This document provides information on the following topics: </p>
  38
  39 <ul>
  40
  41 <li><a href="#using">Using the Postfix fast ETRN service</a>
  42
  43 <li><a href="#how">How Postfix fast ETRN works</a>
  44
  45 <li><a href="#dirty_secret">Postfix fast ETRN service limitations</a>
  46
  47 <li><a href="#config">Configuring the Postfix fast ETRN service</a>
  48
  49 <li><a href="#only">Configuring a domain for ETRN service only</a>
  50
  51 <li><a href="#testing">Testing the Postfix fast ETRN service</a>
  52
  53 </ul>
  54
  55 <p> Other documents with information on this subject: </p>
  56
  57 <ul>
  58
  59 <li> <a href="flush.8.html">flush(8)</a>, flush service implementation
  60
  61 </ul>
  62
  63 <h2><a name="using">Using the Postfix fast ETRN service</a> </h2>
  64
  65 <p> The following is an example SMTP session that shows how an SMTP
  66 client requests the ETRN service. Client commands are shown in bold
  67 font.  </p>
  68
  69 <blockquote>
  70 <pre>
  71 220 my.server.tld ESMTP Postfix
  72 <b>HELO my.client.tld</b>
  73 250 Ok
  74 <b>ETRN some.customer.domain</b>
  75 250 Queuing started
  76 <b>QUIT</b>
  77 221 Bye
  78 </pre>
  79 </blockquote>
  80
  81 <p> As mentioned in the introduction, the mail is delivered by
  82 connecting to the customer's SMTP server; it is not sent over
  83 the connection that was used to send the ETRN command. </p>
  84
  85 <p> The Postfix operator can request delivery for a specific customer
  86 by using the command "sendmail -qR<i>destination</i>" and, with
  87 Postfix version 1.1 and later, "postqueue -s<i>destination</i>".
  88 Access to this feature is controlled with the <a href="postconf.5.html#authorized_flush_users">authorized_flush_users</a>
  89 configuration parameter (Postfix version 2.2 and later).
  90 </p>
  91
  92 <h2><a name="how">How Postfix fast ETRN works</a></h2>
  93
  94 <p> When a Postfix delivery agent decides that mail must be delivered
  95 later, it sends the destination domain name and the queue file name
  96 to the <a href="flush.8.html">flush(8)</a> daemon which maintains per-destination logfiles
  97 with file names of queued mail.  These logfiles are kept below
  98 $<a href="postconf.5.html#queue_directory">queue_directory</a>/flush. Per-destination logfiles are maintained
  99 only for destinations that are listed with the $<a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a>
 100 parameter and that have syntactically valid domain names.  </p>
 101
 102 <blockquote>
 103
 104 <table>
 105
 106 <tr>
 107
 108 <td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br>
 109 delivery<br> agent</td>
 110
 111 <td> <tt>-</tt>(domain, queue ID)<tt>-&gt;</tt> </td>
 112
 113 <td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br>
 114 flush<br> daemon</td>
 115
 116 <td> <tt>-</tt>(queue ID)<tt>-&gt;</tt> </td>
 117
 118 <td bgcolor="#f0f0ff" align="center" valign="middle"> One logfile <br>
 119 per eligible<br> domain </td>
 120
 121 </tr>
 122
 123 </table>
 124
 125 </blockquote>
 126
 127 <p> When Postfix receives a request to "deliver mail for a domain
 128 now", the <a href="flush.8.html">flush(8)</a> daemon moves all <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> files that are
 129 listed for that domain to the <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>, and requests that
 130 the queue manager deliver them. In order to force delivery, the
 131 queue manager temporarily ignores the lists of undeliverable
 132 destinations:  the volatile in-memory list of dead domains, and
 133 the list of message delivery transports specified with the
 134 <a href="postconf.5.html#defer_transports">defer_transports</a> configuration parameter. </p>
 135
 136 <h2><a name="dirty_secret">Postfix fast ETRN service limitations</a></h2>
 137
 138 <p> The design of the <a href="flush.8.html">flush(8)</a> server and of the flush queue
 139 introduce a few limitations that should not be an issue unless you
 140 want to turn on fast ETRN service for every possible destination.
 141 </p>
 142
 143 <ul>
 144
 145 <li> <p> The <a href="flush.8.html">flush(8)</a> daemon maintains per-destination logfiles
 146 with queue file names. When a request to "deliver mail now" arrives,
 147 Postfix will attempt to deliver all recipients in the queue files
 148 that have mail for the destination in question.  This does not
 149 perform well with queue files that have recipients in many different
 150 domains, such as queue files with outbound mailing list traffic.
 151 </p>
 152
 153 <li> <p> The <a href="flush.8.html">flush(8)</a> daemon maintains per-destination logfiles
 154 only for destinations listed with $<a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a>. With other
 155 destinations you cannot request delivery with "sendmail
 156 -qR<i>destination</i>" or, with Postfix version 1.1 and later,
 157 "postqueue -s<i>destination</i>". </p>
 158
 159 <li> <p> Up to and including early versions of Postfix version 2.1,
 160 the "fast flush" service may not deliver some messages if the
 161 request to "deliver mail now" is received while a <a href="QSHAPE_README.html#deferred_queue">deferred queue</a>
 162 scan is already in progress. The reason is that the queue manager
 163 does not ignore the volatile in-memory list of dead domains, and
 164 the list of message delivery transports specified with the
 165 <a href="postconf.5.html#defer_transports">defer_transports</a> configuration parameter.  </p>
 166
 167 <li> <p> Up to and including Postfix version 2.3, the "fast flush"
 168 service may not deliver some messages if the request to "deliver
 169 mail now" arrives while an <a href="QSHAPE_README.html#incoming_queue">incoming queue</a> scan is already in progress.
 170 </p>
 171
 172 </ul>
 173
 174 <h2><a name="config">Configuring the Postfix fast ETRN service</a></h2>
 175
 176 <p> The behavior of the <a href="flush.8.html">flush(8)</a> daemon is controlled by parameters
 177 in the <a href="postconf.5.html">main.cf</a> configuration file. </p>
 178
 179 <p> By default, Postfix "fast ETRN" service is available only for
 180 destinations that Postfix is willing to relay mail to:  </p>
 181
 182 <blockquote>
 183 <pre>
 184 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 185     <a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a> = $<a href="postconf.5.html#relay_domains">relay_domains</a>
 186     <a href="postconf.5.html#smtpd_etrn_restrictions">smtpd_etrn_restrictions</a> = <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, reject
 187 </pre>
 188 </blockquote>
 189
 190 <p> Notes: </p>
 191
 192 <ul>
 193
 194 <li> <p> The <a href="postconf.5.html#relay_domains">relay_domains</a> parameter specifies what destinations
 195 Postfix will relay to.  For destinations that are not eligible for
 196 the "fast ETRN" service, Postfix replies with an error message.
 197 </p>
 198
 199 <li> <p> The <a href="postconf.5.html#smtpd_etrn_restrictions">smtpd_etrn_restrictions</a> parameter limits what clients
 200 may execute the ETRN command. By default, any client has permission.
 201 </p>
 202
 203 </ul>
 204
 205 <p> To enable "fast ETRN" for some other destination, specify: </p>
 206
 207 <blockquote>
 208 <pre>
 209 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 210     <a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a> = $<a href="postconf.5.html#relay_domains">relay_domains</a>, some.other.domain
 211 </pre>
 212 </blockquote>
 213
 214 <p> To disable "fast ETRN", so that Postfix rejects all ETRN requests
 215 and so that it maintains no per-destination logfiles, specify: </p>
 216
 217 <blockquote>
 218 <pre>
 219 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 220     <a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a> =
 221 </pre>
 222 </blockquote>
 223
 224 <h2><a name="only">Configuring a domain for ETRN service only</a></h2>
 225
 226 <p> While an "ETRN" customer is off-line, Postfix will make
 227 spontaneous attempts to deliver mail to it. These attempts are
 228 separated in time by increasing time intervals, ranging from
 229 $<a href="postconf.5.html#minimal_backoff_time">minimal_backoff_time</a> to $<a href="postconf.5.html#maximal_backoff_time">maximal_backoff_time</a>, and should not be
 230 a problem unless a lot of mail is queued. </p>
 231
 232 <p> To prevent Postfix from making spontaneous delivery attempts
 233 you can configure Postfix to always defer mail for the "ETRN"
 234 customer.  Mail is delivered only after the ETRN command or with
 235 "sendmail -q", with "sendmail -qR<i>domain</i>", or with "postqueue
 236 -s<i>domain</i>"(Postfix version 1.1 and later only), </p>
 237
 238 <p> In the example below we configure an "etrn-only" delivery
 239 transport which is simply a duplicate of the "smtp" and "relay"
 240 mail delivery transports. The only difference is that mail destined
 241 for this delivery transport is deferred as soon as it arrives.
 242 </p>
 243
 244 <blockquote>
 245 <pre>
 246  1 /etc/postfix/<a href="master.5.html">master.cf</a>:
 247  2   # =============================================================
 248  3   # service type  private unpriv  chroot  wakeup  maxproc command
 249  4   #               (yes)   (yes)   (yes)   (never) (100)
 250  5   # =============================================================
 251  6   smtp      unix  -       -       n       -       -       smtp
 252  7   relay     unix  -       -       n       -       -       smtp
 253  8   etrn-only unix  -       -       n       -       -       smtp
 254  9
 255 10 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 256 11   <a href="postconf.5.html#relay_domains">relay_domains</a> = customer.tld ...other domains...
 257 12   <a href="postconf.5.html#defer_transports">defer_transports</a> = etrn-only
 258 13   <a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport
 259 14
 260 15 /etc/postfix/transport:
 261 16   customer.tld     etrn-only:[mailhost.customer.tld]
 262 </pre>
 263 </blockquote>
 264
 265 <p>Translation: </p>
 266
 267 <ul>
 268
 269 <li> <p> Line 8: The "etrn-only" mail delivery service is a copy of the
 270 "smtp" and "relay" service. </p>
 271
 272 <li> <p> Line 11: Don't forget to authorize relaying for this
 273 customer, either via <a href="postconf.5.html#relay_domains">relay_domains</a> or with the <a href="postconf.5.html#permit_mx_backup">permit_mx_backup</a>
 274 feature. </p>
 275
 276 <li> <p> Line 12: The "etrn-only" mail delivery service is configured
 277 so that spontaneous mail delivery is disabled. </p>
 278
 279 <li> <p> Lines 13-16: Mail for the customer is given to the
 280 "etrn-only" mail delivery service. </p>
 281
 282 <li> <p> Line 16: The "[mailhost.customer.tld]" turns off MX record
 283 lookups; you must specify this if your Postfix server is the primary
 284 MX host for the customer's domain.  </p>
 285
 286 </ul>
 287
 288 <h2><a name="testing">Testing the Postfix fast ETRN service</a></h2>
 289
 290 <p> By default, "fast ETRN" service is enabled for all domains that
 291 match $<a href="postconf.5.html#relay_domains">relay_domains</a>.  If you run Postfix with "fast ETRN" service
 292 for the very first time, you need to run "sendmail -q" once
 293 in order to populate the per-site deferred mail logfiles.  If you
 294 omit this step, no harm is done.  The logfiles will eventually
 295 become populated as Postfix routinely attempts to deliver delayed
 296 mail, but that will take a couple hours.  After the "sendmail
 297 -q" command has completed all delivery attempts (this can take
 298 a while), you're ready to test the "fast ETRN" service.
 299
 300 <p> To test the "fast ETRN" service, telnet to the Postfix SMTP
 301 server from a client that is allowed to execute ETRN commands (by
 302 default, that's every client), and type the commands shown in
 303 boldface: </p>
 304
 305 <blockquote>
 306 <pre>
 307 220 my.server.tld ESMTP Postfix
 308 <b>HELO my.client.tld</b>
 309 250 Ok
 310 <b>ETRN some.customer.domain</b>
 311 250 Queuing started
 312 </pre>
 313 </blockquote>
 314
 315 <p> where "some.customer.domain" is the name of a domain that has
 316 a non-empty logfile somewhere under $<a href="postconf.5.html#queue_directory">queue_directory</a>/flush. </p>
 317
 318 <p> In the maillog file, you should immediately see a couple of
 319 logfile records, as evidence that the queue manager has opened
 320 queue files: </p>
 321
 322 <blockquote>
 323 <pre>
 324 Oct  2 10:51:19 <a href="postconf.5.html#myhostname">myhostname</a> postfix/qmgr[51999]: 682E8440A4:
 325     from=&lt;whatever&gt;, size=12345, nrcpt=1 (queue active)
 326 Oct  2 10:51:19 <a href="postconf.5.html#myhostname">myhostname</a> postfix/qmgr[51999]: 02249440B7:
 327     from=&lt;whatever&gt;, size=4711, nrcpt=1 (queue active)
 328 </pre>
 329 </blockquote>
 330
 331 <p> What happens next depends on whether the destination is reachable.
 332 If it's not reachable, the mail queue IDs will be added back to
 333 the some.customer.domain logfile under $<a href="postconf.5.html#queue_directory">queue_directory</a>/flush.
 334 </p>
 335
 336 <p> Repeat the exercise with some other destination that your server
 337 is willing to relay to (any domain listed in $<a href="postconf.5.html#relay_domains">relay_domains</a>), but
 338 that has no mail queued. The text in bold face stands for the
 339 commands that you type: </p>
 340
 341 <blockquote>
 342 <pre>
 343 220 my.server.tld ESMTP Postfix
 344 <b>HELO my.client.tld</b>
 345 250 Ok
 346 <b>ETRN some.other.customer.domain</b>
 347 250 Queuing started
 348 </pre>
 349 </blockquote>
 350
 351 <p> This time, the "ETRN"" command should trigger NO mail deliveries
 352 at all. If this triggers delivery of all mail, then you used the
 353 wrong domain name, or "fast ETRN" service is turned off.  </p>
 354
 355 <p> Finally, repeat the exercise with a destination that your mail
 356 server is not willing to relay to.  It does not matter if your
 357 server has mail queued for that destination. </p>
 358
 359 <blockquote>
 360 <pre>
 361 220 my.server.tld ESMTP Postfix
 362 <b>HELO my.client.tld</b>
 363 250 Ok
 364 <b>ETRN not.a.customer.domain</b>
 365 459 &lt;not.a.customer.domain&gt;: service unavailable
 366 </pre>
 367 </blockquote>
 368
 369 <p> In this case, Postfix should reject the request
 370 as shown above. </p>
 371
 372 </body>
 373
 374 </html>