dist/html/ETRN_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix ETRN 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 ETRN Howto</h1>

<hr>

<h2>Purpose of the Postfix fast ETRN service</h2>

<p> The SMTP ETRN command was designed for sites that have intermittent
Internet connectivity. With ETRN, a site can tell the mail server
of its provider to "Please deliver all my mail now". The SMTP server
searches the queue for mail to the customer, and delivers that mail
<b>by connecting to the customer's SMTP server</b>. The mail is
not delivered via the connection that was used for sending ETRN.
</p>

<p> As of version 1.0, Postfix has a fast ETRN implementation that
does not require Postfix to examine every queue file.  Instead,
Postfix maintains a record of what queue files contain mail for
destinations that are configured for ETRN service.  ETRN service
is no longer available for domains that aren't configured for the
service.  </p>

<p> This document provides information on the following topics: </p>

<ul>

<li><a href="#using">Using the Postfix fast ETRN service</a>

<li><a href="#how">How Postfix fast ETRN works</a>

<li><a href="#dirty_secret">Postfix fast ETRN service limitations</a>

<li><a href="#config">Configuring the Postfix fast ETRN service</a>

<li><a href="#only">Configuring a domain for ETRN service only</a>

<li><a href="#testing">Testing the Postfix fast ETRN service</a>

</ul>

<p> Other documents with information on this subject: </p>

<ul>

<li> <a href="flush.8.html">flush(8)</a>, flush service implementation

</ul>

<h2><a name="using">Using the Postfix fast ETRN service</a> </h2>

<p> The following is an example SMTP session that shows how an SMTP
client requests the ETRN service. Client commands are shown in bold
font.  </p>

<blockquote>
<pre>
220 my.server.tld ESMTP Postfix
<b>HELO my.client.tld</b>
250 Ok
<b>ETRN some.customer.domain</b>
250 Queuing started
<b>QUIT</b>
221 Bye
</pre>
</blockquote>

<p> As mentioned in the introduction, the mail is delivered by
connecting to the customer's SMTP server; it is not sent over
the connection that was used to send the ETRN command. </p>

<p> The Postfix operator can request delivery for a specific customer
by using the command "sendmail -qR<i>destination</i>" and, with
Postfix version 1.1 and later, "postqueue -s<i>destination</i>".
Access to this feature is controlled with the <a href="postconf.5.html#authorized_flush_users">authorized_flush_users</a>
configuration parameter (Postfix version 2.2 and later).
</p>

<h2><a name="how">How Postfix fast ETRN works</a></h2>

<p> When a Postfix delivery agent decides that mail must be delivered
later, it sends the destination domain name and the queue file name
to the <a href="flush.8.html">flush(8)</a> daemon which maintains per-destination logfiles
with file names of queued mail.  These logfiles are kept below
$<a href="postconf.5.html#queue_directory">queue_directory</a>/flush. Per-destination logfiles are maintained
only for destinations that are listed with the $<a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a>
parameter and that have syntactically valid domain names.  </p>

<blockquote>

<table>

<tr>

<td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br>
delivery<br> agent</td>

<td> <tt>-</tt>(domain, queue ID)<tt>-&gt;</tt> </td>

<td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br>
flush<br> daemon</td>

<td> <tt>-</tt>(queue ID)<tt>-&gt;</tt> </td>

<td bgcolor="#f0f0ff" align="center" valign="middle"> One logfile <br>
per eligible<br> domain </td>

</tr>

</table>

</blockquote>

<p> When Postfix receives a request to "deliver mail for a domain
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
listed for that domain to the <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>, and requests that
the queue manager deliver them. In order to force delivery, the
queue manager temporarily ignores the lists of undeliverable
destinations:  the volatile in-memory list of dead domains, and
the list of message delivery transports specified with the
<a href="postconf.5.html#defer_transports">defer_transports</a> configuration parameter. </p>

<h2><a name="dirty_secret">Postfix fast ETRN service limitations</a></h2>

<p> The design of the <a href="flush.8.html">flush(8)</a> server and of the flush queue
introduce a few limitations that should not be an issue unless you
want to turn on fast ETRN service for every possible destination.
</p>

<ul>

<li> <p> The <a href="flush.8.html">flush(8)</a> daemon maintains per-destination logfiles
with queue file names. When a request to "deliver mail now" arrives,
Postfix will attempt to deliver all recipients in the queue files
that have mail for the destination in question.  This does not
perform well with queue files that have recipients in many different
domains, such as queue files with outbound mailing list traffic.
</p>

<li> <p> The <a href="flush.8.html">flush(8)</a> daemon maintains per-destination logfiles
only for destinations listed with $<a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a>. With other
destinations you cannot request delivery with "sendmail
-qR<i>destination</i>" or, with Postfix version 1.1 and later,
"postqueue -s<i>destination</i>". </p>

<li> <p> Up to and including early versions of Postfix version 2.1,
the "fast flush" service may not deliver some messages if the
request to "deliver mail now" is received while a <a href="QSHAPE_README.html#deferred_queue">deferred queue</a>
scan is already in progress. The reason is that the queue manager
does not ignore the volatile in-memory list of dead domains, and
the list of message delivery transports specified with the
<a href="postconf.5.html#defer_transports">defer_transports</a> configuration parameter.  </p>

<li> <p> Up to and including Postfix version 2.3, the "fast flush"
service may not deliver some messages if the request to "deliver
mail now" arrives while an <a href="QSHAPE_README.html#incoming_queue">incoming queue</a> scan is already in progress.
</p>

</ul>

<h2><a name="config">Configuring the Postfix fast ETRN service</a></h2>

<p> The behavior of the <a href="flush.8.html">flush(8)</a> daemon is controlled by parameters
in the <a href="postconf.5.html">main.cf</a> configuration file. </p>

<p> By default, Postfix "fast ETRN" service is available only for
destinations that Postfix is willing to relay mail to:  </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a> = $<a href="postconf.5.html#relay_domains">relay_domains</a>
    <a href="postconf.5.html#smtpd_etrn_restrictions">smtpd_etrn_restrictions</a> = <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, reject
</pre>
</blockquote>

<p> Notes: </p>

<ul>

<li> <p> The <a href="postconf.5.html#relay_domains">relay_domains</a> parameter specifies what destinations
Postfix will relay to.  For destinations that are not eligible for
the "fast ETRN" service, Postfix replies with an error message.
</p>

<li> <p> The <a href="postconf.5.html#smtpd_etrn_restrictions">smtpd_etrn_restrictions</a> parameter limits what clients
may execute the ETRN command. By default, any client has permission.
</p>

</ul>

<p> To enable "fast ETRN" for some other destination, specify: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <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
</pre>
</blockquote>

<p> To disable "fast ETRN", so that Postfix rejects all ETRN requests
and so that it maintains no per-destination logfiles, specify: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#fast_flush_domains">fast_flush_domains</a> =
</pre>
</blockquote>

<h2><a name="only">Configuring a domain for ETRN service only</a></h2>

<p> While an "ETRN" customer is off-line, Postfix will make
spontaneous attempts to deliver mail to it. These attempts are
separated in time by increasing time intervals, ranging from
$<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
a problem unless a lot of mail is queued. </p>

<p> To prevent Postfix from making spontaneous delivery attempts
you can configure Postfix to always defer mail for the "ETRN"
customer.  Mail is delivered only after the ETRN command or with
"sendmail -q", with "sendmail -qR<i>domain</i>", or with "postqueue
-s<i>domain</i>"(Postfix version 1.1 and later only), </p>

<p> In the example below we configure an "etrn-only" delivery
transport which is simply a duplicate of the "smtp" and "relay"
mail delivery transports. The only difference is that mail destined
for this delivery transport is deferred as soon as it arrives.
</p>

<blockquote>
<pre>
 1 /etc/postfix/<a href="master.5.html">master.cf</a>:
 2   # =============================================================
 3   # service type  private unpriv  chroot  wakeup  maxproc command
 4   #               (yes)   (yes)   (yes)   (never) (100)
 5   # =============================================================
 6   smtp      unix  -       -       n       -       -       smtp
 7   relay     unix  -       -       n       -       -       smtp
 8   etrn-only unix  -       -       n       -       -       smtp
 9
10 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
11   <a href="postconf.5.html#relay_domains">relay_domains</a> = customer.tld ...other domains...
12   <a href="postconf.5.html#defer_transports">defer_transports</a> = etrn-only
13   <a href="postconf.5.html#transport_maps">transport_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport
14
15 /etc/postfix/transport:
16   customer.tld     etrn-only:[mailhost.customer.tld]
</pre>
</blockquote>

<p>Translation: </p>

<ul>

<li> <p> Line 8: The "etrn-only" mail delivery service is a copy of the
"smtp" and "relay" service. </p>

<li> <p> Line 11: Don't forget to authorize relaying for this
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>
feature. </p>

<li> <p> Line 12: The "etrn-only" mail delivery service is configured
so that spontaneous mail delivery is disabled. </p>

<li> <p> Lines 13-16: Mail for the customer is given to the
"etrn-only" mail delivery service. </p>

<li> <p> Line 16: The "[mailhost.customer.tld]" turns off MX record
lookups; you must specify this if your Postfix server is the primary
MX host for the customer's domain.  </p>

</ul>

<h2><a name="testing">Testing the Postfix fast ETRN service</a></h2>

<p> By default, "fast ETRN" service is enabled for all domains that
match $<a href="postconf.5.html#relay_domains">relay_domains</a>.  If you run Postfix with "fast ETRN" service
for the very first time, you need to run "sendmail -q" once
in order to populate the per-site deferred mail logfiles.  If you
omit this step, no harm is done.  The logfiles will eventually
become populated as Postfix routinely attempts to deliver delayed
mail, but that will take a couple hours.  After the "sendmail
-q" command has completed all delivery attempts (this can take
a while), you're ready to test the "fast ETRN" service.

<p> To test the "fast ETRN" service, telnet to the Postfix SMTP
server from a client that is allowed to execute ETRN commands (by
default, that's every client), and type the commands shown in
boldface: </p>

<blockquote>
<pre>
220 my.server.tld ESMTP Postfix
<b>HELO my.client.tld</b>
250 Ok
<b>ETRN some.customer.domain</b>
250 Queuing started
</pre>
</blockquote>

<p> where "some.customer.domain" is the name of a domain that has
a non-empty logfile somewhere under $<a href="postconf.5.html#queue_directory">queue_directory</a>/flush. </p>

<p> In the maillog file, you should immediately see a couple of
logfile records, as evidence that the queue manager has opened
queue files: </p>

<blockquote>
<pre>
Oct  2 10:51:19 <a href="postconf.5.html#myhostname">myhostname</a> postfix/qmgr[51999]: 682E8440A4:
    from=&lt;whatever&gt;, size=12345, nrcpt=1 (queue active)
Oct  2 10:51:19 <a href="postconf.5.html#myhostname">myhostname</a> postfix/qmgr[51999]: 02249440B7:
    from=&lt;whatever&gt;, size=4711, nrcpt=1 (queue active)
</pre>
</blockquote>

<p> What happens next depends on whether the destination is reachable.
If it's not reachable, the mail queue IDs will be added back to
the some.customer.domain logfile under $<a href="postconf.5.html#queue_directory">queue_directory</a>/flush.
</p>

<p> Repeat the exercise with some other destination that your server
is willing to relay to (any domain listed in $<a href="postconf.5.html#relay_domains">relay_domains</a>), but
that has no mail queued. The text in bold face stands for the
commands that you type: </p>

<blockquote>
<pre>
220 my.server.tld ESMTP Postfix
<b>HELO my.client.tld</b>
250 Ok
<b>ETRN some.other.customer.domain</b>
250 Queuing started
</pre>
</blockquote>

<p> This time, the "ETRN"" command should trigger NO mail deliveries
at all. If this triggers delivery of all mail, then you used the
wrong domain name, or "fast ETRN" service is turned off.  </p>

<p> Finally, repeat the exercise with a destination that your mail
server is not willing to relay to.  It does not matter if your
server has mail queued for that destination. </p>

<blockquote>
<pre>
220 my.server.tld ESMTP Postfix
<b>HELO my.client.tld</b>
250 Ok
<b>ETRN not.a.customer.domain</b>
459 &lt;not.a.customer.domain&gt;: service unavailable
</pre>
</blockquote>

<p> In this case, Postfix should reject the request
as shown above. </p>

</body>

</html>