<!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=us-ascii"> </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> flush(8), 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 authorized_flush_users 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 flush(8) daemon which maintains per-destination logfiles with file names of queued mail. These logfiles are kept below $queue_directory/flush. Per-destination logfiles are maintained only for destinations that are listed with the $fast_flush_domains 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 flush(8) daemon moves all deferred queue files that are listed for that domain to the incoming queue, 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 defer_transports configuration parameter. </p> <h2><a name="dirty_secret">Postfix fast ETRN service limitations</a></h2> <p> The design of the flush(8) 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 flush(8) 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 flush(8) daemon maintains per-destination logfiles only for destinations listed with $fast_flush_domains. 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 deferred queue 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 defer_transports 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 incoming queue scan is already in progress. </p> </ul> <h2><a name="config">Configuring the Postfix fast ETRN service</a></h2> <p> The behavior of the flush(8) daemon is controlled by parameters in the main.cf 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/main.cf: fast_flush_domains = $relay_domains smtpd_etrn_restrictions = permit_mynetworks, reject </pre> </blockquote> <p> Notes: </p> <ul> <li> <p> The relay_domains 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 smtpd_etrn_restrictions 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/main.cf: fast_flush_domains = $relay_domains, 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/main.cf: fast_flush_domains = </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 $minimal_backoff_time to $maximal_backoff_time, 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/master.cf: 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/main.cf: 11 relay_domains = customer.tld ...other domains... 12 defer_transports = etrn-only 13 transport_maps = hash:/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 relay_domains or with the permit_mx_backup 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 $relay_domains. 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 $queue_directory/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 myhostname postfix/qmgr[51999]: 682E8440A4: from=<whatever>, size=12345, nrcpt=1 (queue active) Oct 2 10:51:19 myhostname 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 $queue_directory/flush. </p> <p> Repeat the exercise with some other destination that your server is willing to relay to (any domain listed in $relay_domains), 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>