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