external/ibm-public/postfix/dist/README_FILES/ETRN_README

   1 P\bPo\bos\bst\btf\bfi\bix\bx E\bET\bTR\bRN\bN H\bHo\bow\bwt\bto\bo
   2
   3 -------------------------------------------------------------------------------
   4
   5 P\bPu\bur\brp\bpo\bos\bse\be o\bof\bf t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be
   6
   7 The SMTP ETRN command was designed for sites that have intermittent Internet
   8 connectivity. With ETRN, a site can tell the mail server of its provider to
   9 "Please deliver all my mail now". The SMTP server searches the queue for mail
  10 to the customer, and delivers that mail b\bby\by c\bco\bon\bnn\bne\bec\bct\bti\bin\bng\bg t\bto\bo t\bth\bhe\be c\bcu\bus\bst\bto\bom\bme\ber\br'\b's\bs S\bSM\bMT\bTP\bP
  11 s\bse\ber\brv\bve\ber\br. The mail is not delivered via the connection that was used for sending
  12 ETRN.
  13
  14 As of version 1.0, Postfix has a fast ETRN implementation that does not require
  15 Postfix to examine every queue file. Instead, Postfix maintains a record of
  16 what queue files contain mail for destinations that are configured for ETRN
  17 service. ETRN service is no longer available for domains that aren't configured
  18 for the service.
  19
  20 This document provides information on the following topics:
  21
  22   * Using the Postfix fast ETRN service
  23   * How Postfix fast ETRN works
  24   * Postfix fast ETRN service limitations
  25   * Configuring the Postfix fast ETRN service
  26   * Configuring a domain for ETRN service only
  27   * Testing the Postfix fast ETRN service
  28
  29 Other documents with information on this subject:
  30
  31   * flush(8), flush service implementation
  32
  33 U\bUs\bsi\bin\bng\bg t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be
  34
  35 The following is an example SMTP session that shows how an SMTP client requests
  36 the ETRN service. Client commands are shown in bold font.
  37
  38     220 my.server.tld ESMTP Postfix
  39     H\bHE\bEL\bLO\bO m\bmy\by.\b.c\bcl\bli\bie\ben\bnt\bt.\b.t\btl\bld\bd
  40     250 Ok
  41     E\bET\bTR\bRN\bN s\bso\bom\bme\be.\b.c\bcu\bus\bst\bto\bom\bme\ber\br.\b.d\bdo\bom\bma\bai\bin\bn
  42     250 Queuing started
  43     Q\bQU\bUI\bIT\bT
  44     221 Bye
  45
  46 As mentioned in the introduction, the mail is delivered by connecting to the
  47 customer's SMTP server; it is not sent over the connection that was used to
  48 send the ETRN command.
  49
  50 The Postfix operator can request delivery for a specific customer by using the
  51 command "sendmail -qRdestination" and, with Postfix version 1.1 and later,
  52 "postqueue -sdestination". Access to this feature is controlled with the
  53 authorized_flush_users configuration parameter (Postfix version 2.2 and later).
  54
  55 H\bHo\bow\bw P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN w\bwo\bor\brk\bks\bs
  56
  57 When a Postfix delivery agent decides that mail must be delivered later, it
  58 sends the destination domain name and the queue file name to the flush(8)
  59 daemon which maintains per-destination logfiles with file names of queued mail.
  60 These logfiles are kept below $queue_directory/flush. Per-destination logfiles
  61 are maintained only for destinations that are listed with the
  62 $fast_flush_domains parameter and that have syntactically valid domain names.
  63
  64     Postfix                        Postfix               One logfile
  65     delivery -(domain, queue ID)->  flush  -(queue ID)-> per eligible
  66      agent                         daemon                   domain
  67
  68 When Postfix receives a request to "deliver mail for a domain now", the flush
  69 (8) daemon moves all deferred queue files that are listed for that domain to
  70 the incoming queue, and requests that the queue manager deliver them. In order
  71 to force delivery, the queue manager temporarily ignores the lists of
  72 undeliverable destinations: the volatile in-memory list of dead domains, and
  73 the list of message delivery transports specified with the defer_transports
  74 configuration parameter.
  75
  76 P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be l\bli\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
  77
  78 The design of the flush(8) server and of the flush queue introduce a few
  79 limitations that should not be an issue unless you want to turn on fast ETRN
  80 service for every possible destination.
  81
  82   * The flush(8) daemon maintains per-destination logfiles with queue file
  83     names. When a request to "deliver mail now" arrives, Postfix will attempt
  84     to deliver all recipients in the queue files that have mail for the
  85     destination in question. This does not perform well with queue files that
  86     have recipients in many different domains, such as queue files with
  87     outbound mailing list traffic.
  88
  89   * The flush(8) daemon maintains per-destination logfiles only for
  90     destinations listed with $fast_flush_domains. With other destinations you
  91     cannot request delivery with "sendmail -qRdestination" or, with Postfix
  92     version 1.1 and later, "postqueue -sdestination".
  93
  94   * Up to and including early versions of Postfix version 2.1, the "fast flush"
  95     service may not deliver some messages if the request to "deliver mail now"
  96     is received while a deferred queue scan is already in progress. The reason
  97     is that the queue manager does not ignore the volatile in-memory list of
  98     dead domains, and the list of message delivery transports specified with
  99     the defer_transports configuration parameter.
 100
 101   * Up to and including Postfix version 2.3, the "fast flush" service may not
 102     deliver some messages if the request to "deliver mail now" arrives while an
 103     incoming queue scan is already in progress.
 104
 105 C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be
 106
 107 The behavior of the flush(8) daemon is controlled by parameters in the main.cf
 108 configuration file.
 109
 110 By default, Postfix "fast ETRN" service is available only for destinations that
 111 Postfix is willing to relay mail to:
 112
 113     /etc/postfix/main.cf:
 114         fast_flush_domains = $relay_domains
 115         smtpd_etrn_restrictions = permit_mynetworks, reject
 116
 117 Notes:
 118
 119   * The relay_domains parameter specifies what destinations Postfix will relay
 120     to. For destinations that are not eligible for the "fast ETRN" service,
 121     Postfix replies with an error message.
 122
 123   * The smtpd_etrn_restrictions parameter limits what clients may execute the
 124     ETRN command. By default, any client has permission.
 125
 126 To enable "fast ETRN" for some other destination, specify:
 127
 128     /etc/postfix/main.cf:
 129         fast_flush_domains = $relay_domains, some.other.domain
 130
 131 To disable "fast ETRN", so that Postfix rejects all ETRN requests and so that
 132 it maintains no per-destination logfiles, specify:
 133
 134     /etc/postfix/main.cf:
 135         fast_flush_domains =
 136
 137 C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg a\ba d\bdo\bom\bma\bai\bin\bn f\bfo\bor\br E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be o\bon\bnl\bly\by
 138
 139 While an "ETRN" customer is off-line, Postfix will make spontaneous attempts to
 140 deliver mail to it. These attempts are separated in time by increasing time
 141 intervals, ranging from $minimal_backoff_time to $maximal_backoff_time, and
 142 should not be a problem unless a lot of mail is queued.
 143
 144 To prevent Postfix from making spontaneous delivery attempts you can configure
 145 Postfix to always defer mail for the "ETRN" customer. Mail is delivered only
 146 after the ETRN command or with "sendmail -q", with "sendmail -qRdomain", or
 147 with "postqueue -sdomain"(Postfix version 1.1 and later only),
 148
 149 In the example below we configure an "etrn-only" delivery transport which is
 150 simply a duplicate of the "smtp" and "relay" mail delivery transports. The only
 151 difference is that mail destined for this delivery transport is deferred as
 152 soon as it arrives.
 153
 154      1 /etc/postfix/master.cf:
 155      2   # =============================================================
 156      3   # service type  private unpriv  chroot  wakeup  maxproc command
 157      4   #               (yes)   (yes)   (yes)   (never) (100)
 158      5   # =============================================================
 159      6   smtp      unix  -       -       n       -       -       smtp
 160      7   relay     unix  -       -       n       -       -       smtp
 161      8   etrn-only unix  -       -       n       -       -       smtp
 162      9
 163     10 /etc/postfix/main.cf:
 164     11   relay_domains = customer.tld ...other domains...
 165     12   defer_transports = etrn-only
 166     13   transport_maps = hash:/etc/postfix/transport
 167     14
 168     15 /etc/postfix/transport:
 169     16   customer.tld     etrn-only:[mailhost.customer.tld]
 170
 171 Translation:
 172
 173   * Line 8: The "etrn-only" mail delivery service is a copy of the "smtp" and
 174     "relay" service.
 175
 176   * Line 11: Don't forget to authorize relaying for this customer, either via
 177     relay_domains or with the permit_mx_backup feature.
 178
 179   * Line 12: The "etrn-only" mail delivery service is configured so that
 180     spontaneous mail delivery is disabled.
 181
 182   * Lines 13-16: Mail for the customer is given to the "etrn-only" mail
 183     delivery service.
 184
 185   * Line 16: The "[mailhost.customer.tld]" turns off MX record lookups; you
 186     must specify this if your Postfix server is the primary MX host for the
 187     customer's domain.
 188
 189 T\bTe\bes\bst\bti\bin\bng\bg t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx f\bfa\bas\bst\bt E\bET\bTR\bRN\bN s\bse\ber\brv\bvi\bic\bce\be
 190
 191 By default, "fast ETRN" service is enabled for all domains that match
 192 $relay_domains. If you run Postfix with "fast ETRN" service for the very first
 193 time, you need to run "sendmail -q" once in order to populate the per-site
 194 deferred mail logfiles. If you omit this step, no harm is done. The logfiles
 195 will eventually become populated as Postfix routinely attempts to deliver
 196 delayed mail, but that will take a couple hours. After the "sendmail -q"
 197 command has completed all delivery attempts (this can take a while), you're
 198 ready to test the "fast ETRN" service.
 199
 200 To test the "fast ETRN" service, telnet to the Postfix SMTP server from a
 201 client that is allowed to execute ETRN commands (by default, that's every
 202 client), and type the commands shown in boldface:
 203
 204     220 my.server.tld ESMTP Postfix
 205     H\bHE\bEL\bLO\bO m\bmy\by.\b.c\bcl\bli\bie\ben\bnt\bt.\b.t\btl\bld\bd
 206     250 Ok
 207     E\bET\bTR\bRN\bN s\bso\bom\bme\be.\b.c\bcu\bus\bst\bto\bom\bme\ber\br.\b.d\bdo\bom\bma\bai\bin\bn
 208     250 Queuing started
 209
 210 where "some.customer.domain" is the name of a domain that has a non-empty
 211 logfile somewhere under $queue_directory/flush.
 212
 213 In the maillog file, you should immediately see a couple of logfile records, as
 214 evidence that the queue manager has opened queue files:
 215
 216     Oct  2 10:51:19 myhostname postfix/qmgr[51999]: 682E8440A4:
 217         from=<whatever>, size=12345, nrcpt=1 (queue active)
 218     Oct  2 10:51:19 myhostname postfix/qmgr[51999]: 02249440B7:
 219         from=<whatever>, size=4711, nrcpt=1 (queue active)
 220
 221 What happens next depends on whether the destination is reachable. If it's not
 222 reachable, the mail queue IDs will be added back to the some.customer.domain
 223 logfile under $queue_directory/flush.
 224
 225 Repeat the exercise with some other destination that your server is willing to
 226 relay to (any domain listed in $relay_domains), but that has no mail queued.
 227 The text in bold face stands for the commands that you type:
 228
 229     220 my.server.tld ESMTP Postfix
 230     H\bHE\bEL\bLO\bO m\bmy\by.\b.c\bcl\bli\bie\ben\bnt\bt.\b.t\btl\bld\bd
 231     250 Ok
 232     E\bET\bTR\bRN\bN s\bso\bom\bme\be.\b.o\bot\bth\bhe\ber\br.\b.c\bcu\bus\bst\bto\bom\bme\ber\br.\b.d\bdo\bom\bma\bai\bin\bn
 233     250 Queuing started
 234
 235 This time, the "ETRN"" command should trigger NO mail deliveries at all. If
 236 this triggers delivery of all mail, then you used the wrong domain name, or
 237 "fast ETRN" service is turned off.
 238
 239 Finally, repeat the exercise with a destination that your mail server is not
 240 willing to relay to. It does not matter if your server has mail queued for that
 241 destination.
 242
 243     220 my.server.tld ESMTP Postfix
 244     H\bHE\bEL\bLO\bO m\bmy\by.\b.c\bcl\bli\bie\ben\bnt\bt.\b.t\btl\bld\bd
 245     250 Ok
 246     E\bET\bTR\bRN\bN n\bno\bot\bt.\b.a\ba.\b.c\bcu\bus\bst\bto\bom\bme\ber\br.\b.d\bdo\bom\bma\bai\bin\bn
 247     459 <not.a.customer.domain>: service unavailable
 248
 249 In this case, Postfix should reject the request as shown above.
 250