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 23Internet connectivity. With ETRN, a site can tell the mail server 24of its provider to "Please deliver all my mail now". The SMTP server 25searches 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 27not 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 31does not require Postfix to examine every queue file. Instead, 32Postfix maintains a record of what queue files contain mail for 33destinations that are configured for ETRN service. ETRN service 34is no longer available for domains that aren't configured for the 35service. </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> flush(8), 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 66client requests the ETRN service. Client commands are shown in bold 67font. </p> 68 69<blockquote> 70<pre> 71220 my.server.tld ESMTP Postfix 72<b>HELO my.client.tld</b> 73250 Ok 74<b>ETRN some.customer.domain</b> 75250 Queuing started 76<b>QUIT</b> 77221 Bye 78</pre> 79</blockquote> 80 81<p> As mentioned in the introduction, the mail is delivered by 82connecting to the customer's SMTP server; it is not sent over 83the connection that was used to send the ETRN command. </p> 84 85<p> The Postfix operator can request delivery for a specific customer 86by using the command "sendmail -qR<i>destination</i>" and, with 87Postfix version 1.1 and later, "postqueue -s<i>destination</i>". 88Access to this feature is controlled with the authorized_flush_users 89configuration 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 95later, it sends the destination domain name and the queue file name 96to the flush(8) daemon which maintains per-destination logfiles 97with file names of queued mail. These logfiles are kept below 98$queue_directory/flush. Per-destination logfiles are maintained 99only for destinations that are listed with the $fast_flush_domains 100parameter 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> 109delivery<br> agent</td> 110 111<td> <tt>-</tt>(domain, queue ID)<tt>-></tt> </td> 112 113<td bgcolor="#f0f0ff" align="center" valign="middle"> Postfix<br> 114flush<br> daemon</td> 115 116<td> <tt>-</tt>(queue ID)<tt>-></tt> </td> 117 118<td bgcolor="#f0f0ff" align="center" valign="middle"> One logfile <br> 119per 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 128now", the flush(8) daemon moves all deferred queue files that are 129listed for that domain to the incoming queue, and requests that 130the queue manager deliver them. In order to force delivery, the 131queue manager temporarily ignores the lists of undeliverable 132destinations: the volatile in-memory list of dead domains, and 133the list of message delivery transports specified with the 134defer_transports configuration parameter. </p> 135 136<h2><a name="dirty_secret">Postfix fast ETRN service limitations</a></h2> 137 138<p> The design of the flush(8) server and of the flush queue 139introduce a few limitations that should not be an issue unless you 140want to turn on fast ETRN service for every possible destination. 141</p> 142 143<ul> 144 145<li> <p> The flush(8) daemon maintains per-destination logfiles 146with queue file names. When a request to "deliver mail now" arrives, 147Postfix will attempt to deliver all recipients in the queue files 148that have mail for the destination in question. This does not 149perform well with queue files that have recipients in many different 150domains, such as queue files with outbound mailing list traffic. 151</p> 152 153<li> <p> The flush(8) daemon maintains per-destination logfiles 154only for destinations listed with $fast_flush_domains. With other 155destinations 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, 160the "fast flush" service may not deliver some messages if the 161request to "deliver mail now" is received while a deferred queue 162scan is already in progress. The reason is that the queue manager 163does not ignore the volatile in-memory list of dead domains, and 164the list of message delivery transports specified with the 165defer_transports configuration parameter. </p> 166 167<li> <p> Up to and including Postfix version 2.3, the "fast flush" 168service may not deliver some messages if the request to "deliver 169mail now" arrives while an incoming queue 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 flush(8) daemon is controlled by parameters 177in the main.cf configuration file. </p> 178 179<p> By default, Postfix "fast ETRN" service is available only for 180destinations that Postfix is willing to relay mail to: </p> 181 182<blockquote> 183<pre> 184/etc/postfix/main.cf: 185 fast_flush_domains = $relay_domains 186 smtpd_etrn_restrictions = permit_mynetworks, reject 187</pre> 188</blockquote> 189 190<p> Notes: </p> 191 192<ul> 193 194<li> <p> The relay_domains parameter specifies what destinations 195Postfix will relay to. For destinations that are not eligible for 196the "fast ETRN" service, Postfix replies with an error message. 197</p> 198 199<li> <p> The smtpd_etrn_restrictions parameter limits what clients 200may 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/main.cf: 210 fast_flush_domains = $relay_domains, some.other.domain 211</pre> 212</blockquote> 213 214<p> To disable "fast ETRN", so that Postfix rejects all ETRN requests 215and so that it maintains no per-destination logfiles, specify: </p> 216 217<blockquote> 218<pre> 219/etc/postfix/main.cf: 220 fast_flush_domains = 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 227spontaneous attempts to deliver mail to it. These attempts are 228separated in time by increasing time intervals, ranging from 229$minimal_backoff_time to $maximal_backoff_time, and should not be 230a problem unless a lot of mail is queued. </p> 231 232<p> To prevent Postfix from making spontaneous delivery attempts 233you can configure Postfix to always defer mail for the "ETRN" 234customer. 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 239transport which is simply a duplicate of the "smtp" and "relay" 240mail delivery transports. The only difference is that mail destined 241for this delivery transport is deferred as soon as it arrives. 242</p> 243 244<blockquote> 245<pre> 246 1 /etc/postfix/master.cf: 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 25510 /etc/postfix/main.cf: 25611 relay_domains = customer.tld ...other domains... 25712 defer_transports = etrn-only 25813 transport_maps = hash:/etc/postfix/transport 25914 26015 /etc/postfix/transport: 26116 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 273customer, either via relay_domains or with the permit_mx_backup 274feature. </p> 275 276<li> <p> Line 12: The "etrn-only" mail delivery service is configured 277so 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 283lookups; you must specify this if your Postfix server is the primary 284MX 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 291match $relay_domains. If you run Postfix with "fast ETRN" service 292for the very first time, you need to run "sendmail -q" once 293in order to populate the per-site deferred mail logfiles. If you 294omit this step, no harm is done. The logfiles will eventually 295become populated as Postfix routinely attempts to deliver delayed 296mail, but that will take a couple hours. After the "sendmail 297-q" command has completed all delivery attempts (this can take 298a while), you're ready to test the "fast ETRN" service. 299 300<p> To test the "fast ETRN" service, telnet to the Postfix SMTP 301server from a client that is allowed to execute ETRN commands (by 302default, that's every client), and type the commands shown in 303boldface: </p> 304 305<blockquote> 306<pre> 307220 my.server.tld ESMTP Postfix 308<b>HELO my.client.tld</b> 309250 Ok 310<b>ETRN some.customer.domain</b> 311250 Queuing started 312</pre> 313</blockquote> 314 315<p> where "some.customer.domain" is the name of a domain that has 316a non-empty logfile somewhere under $queue_directory/flush. </p> 317 318<p> In the maillog file, you should immediately see a couple of 319logfile records, as evidence that the queue manager has opened 320queue files: </p> 321 322<blockquote> 323<pre> 324Oct 2 10:51:19 myhostname postfix/qmgr[51999]: 682E8440A4: 325 from=<whatever>, size=12345, nrcpt=1 (queue active) 326Oct 2 10:51:19 myhostname postfix/qmgr[51999]: 02249440B7: 327 from=<whatever>, size=4711, nrcpt=1 (queue active) 328</pre> 329</blockquote> 330 331<p> What happens next depends on whether the destination is reachable. 332If it's not reachable, the mail queue IDs will be added back to 333the some.customer.domain logfile under $queue_directory/flush. 334</p> 335 336<p> Repeat the exercise with some other destination that your server 337is willing to relay to (any domain listed in $relay_domains), but 338that has no mail queued. The text in bold face stands for the 339commands that you type: </p> 340 341<blockquote> 342<pre> 343220 my.server.tld ESMTP Postfix 344<b>HELO my.client.tld</b> 345250 Ok 346<b>ETRN some.other.customer.domain</b> 347250 Queuing started 348</pre> 349</blockquote> 350 351<p> This time, the "ETRN"" command should trigger NO mail deliveries 352at all. If this triggers delivery of all mail, then you used the 353wrong domain name, or "fast ETRN" service is turned off. </p> 354 355<p> Finally, repeat the exercise with a destination that your mail 356server is not willing to relay to. It does not matter if your 357server has mail queued for that destination. </p> 358 359<blockquote> 360<pre> 361220 my.server.tld ESMTP Postfix 362<b>HELO my.client.tld</b> 363250 Ok 364<b>ETRN not.a.customer.domain</b> 365459 <not.a.customer.domain>: service unavailable 366</pre> 367</blockquote> 368 369<p> In this case, Postfix should reject the request 370as shown above. </p> 371 372</body> 373 374</html> 375