diff options
Diffstat (limited to 'html/ETRN_README.html')
| -rw-r--r-- | html/ETRN_README.html | 374 |
1 files changed, 374 insertions, 0 deletions
diff --git a/html/ETRN_README.html b/html/ETRN_README.html new file mode 100644 index 0000000..f1d728f --- /dev/null +++ b/html/ETRN_README.html @@ -0,0 +1,374 @@ +<!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"> + +</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>-></tt> </td> + +<td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br> +flush<br> daemon</td> + +<td> <tt>-</tt>(queue ID)<tt>-></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=<whatever>, size=12345, nrcpt=1 (queue active) +Oct 2 10:51:19 <a href="postconf.5.html#myhostname">myhostname</a> postfix/qmgr[51999]: 02249440B7: + from=<whatever>, 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 <not.a.customer.domain>: service unavailable +</pre> +</blockquote> + +<p> In this case, Postfix should reject the request +as shown above. </p> + +</body> + +</html> |