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

   1 P\bPo\bos\bst\btf\bfi\bix\bx C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn C\bCa\bac\bch\bhe\be
   2
   3 -------------------------------------------------------------------------------
   4
   5 I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn
   6
   7 This document describes the Postfix connection cache implementation, which is
   8 available with Postfix version 2.2 and later.
   9
  10 Topics covered in this document:
  11
  12   * What SMTP connection caching can do for you
  13   * Connection cache implementation
  14   * Connection cache configuration
  15   * Connection cache safety mechanisms
  16   * Connection cache limitations
  17   * Connection cache statistics
  18
  19 W\bWh\bha\bat\bt S\bSM\bMT\bTP\bP c\bco\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhi\bin\bng\bg c\bca\ban\bn d\bdo\bo f\bfo\bor\br y\byo\bou\bu
  20
  21 With SMTP connection caching, Postfix can deliver multiple messages over the
  22 same SMTP connection. By default, Postfix 2.2 reuses an SMTP connection
  23 automatically when a destination has high volume of mail in the active queue.
  24
  25 SMTP Connection caching is a performance feature. Whether or not it actually
  26 improves performance depends on the conditions:
  27
  28   * SMTP Connection caching can greatly improve performance when delivering
  29     mail to a destination with multiple mail servers, because it can help
  30     Postfix to skip over a non-responding server.
  31
  32   * Otherwise, the benefits of SMTP connection caching are minor: it eliminates
  33     the latency of the TCP handshake (SYN, SYN+ACK, ACK), plus the latency of
  34     the SMTP initial handshake (220 greeting, EHLO command, EHLO response).
  35
  36   * SMTP Connection caching gives no gains with respect to SMTP session tear-
  37     down. The Postfix smtp(8) client normally does not wait for the server's
  38     reply to the QUIT command, and it never waits for the TCP final handshake
  39     to complete.
  40
  41   * SMTP Connection caching introduces some overhead: the client needs to send
  42     an RSET command to find out if a connection is still usable, before it can
  43     send the next MAIL FROM command.
  44
  45 For other potential issues with SMTP connection caching, see the discussion of
  46 limitations at the end of this document.
  47
  48 C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhe\be i\bim\bmp\bpl\ble\bem\bme\ben\bnt\bta\bat\bti\bio\bon\bn
  49
  50 For an overview of how Postfix delivers mail, see the Postfix architecture
  51 OVERVIEW document.
  52
  53 The Postfix connection cache is shared among Postfix mail delivering processes.
  54 This maximizes the opportunity to reuse an open connection. Other MTAs such as
  55 Sendmail or exim have a non-shared connection cache. Here, a connection can be
  56 reused only by the mail delivering process that creates the connection. To get
  57 the same performance improvement as with a shared connection cache, non-shared
  58 connections need to be kept open for a longer time.
  59
  60 The scache(8) server, introduced with Postfix version 2.2, maintains the shared
  61 connection cache. With Postfix version 2.2, only the smtp(8) client has support
  62 to access this cache.
  63
  64             /-- smtp(8) --> Internet
  65
  66     qmgr(8)       |
  67                   |
  68             \--   | smtp(8) --> Internet
  69                   |
  70                   ^
  71                   |
  72
  73                   scache(8)
  74
  75 When SMTP connection caching is enabled (see next section), the smtp(8) client
  76 does not disconnect after a mail transaction, but gives the connection to the
  77 scache(8) server which keeps the connection open for a limited amount of time.
  78
  79 After handing over the open connection to the scache(8) server, the smtp(8)
  80 client continues with some other mail delivery request. Meanwhile, any smtp(8)
  81 client process can ask the scache(8) server for that cached connection and
  82 reuse it for mail delivery.
  83
  84 The connection cache can be searched by destination domain name (the right-hand
  85 side of the recipient address) and by the IP address of the host at the other
  86 end of the connection. This allows Postfix to reuse a connection even when the
  87 remote host is mail server for domains with different names.
  88
  89 C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhe\be c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn
  90
  91 The Postfix smtp(8) client supports two connection caching strategies:
  92
  93   * On-demand connection caching. This is enabled by default, and is controlled
  94     with the smtp_connection_cache_on_demand configuration parameter. When this
  95     feature is enabled, the Postfix smtp(8) client automatically saves a
  96     connection to the connection cache when a destination has a high volume of
  97     mail in the active queue.
  98
  99     Example:
 100
 101         /etc/postfix/main.cf:
 102             smtp_connection_cache_on_demand = yes
 103
 104   * Per-destination connection caching. This is enabled by explicitly listing
 105     specific destinations with the smtp_connection_cache_destinations
 106     configuration parameter. After completing delivery to a selected
 107     destination, the Postfix smtp(8) client always saves the connection to the
 108     connection cache.
 109
 110     Specify a comma or white space separated list of destinations or pseudo-
 111     destinations:
 112
 113       o if mail is sent without a relay host: a domain name (the right-hand
 114         side of an email address, without the [] around a numeric IP address),
 115
 116       o if mail is sent via a relay host: a relay host name (without the [] or
 117         non-default TCP port), as specified in main.cf or in the transport map,
 118
 119       o a /file/name with domain names and/or relay host names as defined
 120         above,
 121
 122       o a "type:table" with domain names and/or relay host names on the left-
 123         hand side. The right-hand side result from "type:table" lookups is
 124         ignored.
 125
 126     Examples:
 127
 128         /etc/postfix/main.cf:
 129             smtp_connection_cache_destinations = $relayhost
 130             smtp_connection_cache_destinations = hotmail.com, ...
 131             smtp_connection_cache_destinations = static:all (not recommended)
 132
 133 C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhe\be s\bsa\baf\bfe\bet\bty\by m\bme\bec\bch\bha\ban\bni\bis\bsm\bms\bs
 134
 135 Connection caching must be used wisely. It is anti-social to keep an unused
 136 SMTP connection open for a significant amount of time, and it is unwise to send
 137 huge numbers of messages through the same connection. In order to avoid
 138 problems with SMTP connection caching, Postfix implements the following safety
 139 mechanisms:
 140
 141   * The Postfix scache(8) server keeps a connection open for only a limited
 142     time. The time limit is specified with the smtp_connection_cache_time_limit
 143     and with the connection_cache_ttl_limit configuration parameters. This
 144     prevents anti-social behavior.
 145
 146   * The Postfix smtp(8) client reuses a session for only a limited number of
 147     times. This avoids triggering bugs in implementations that do not correctly
 148     handle multiple deliveries per session.
 149
 150     With Postfix 2.2 the use count is limited with the
 151     smtp_connection_cache_reuse_limit configuration parameter. With Postfix 2.3
 152     this is replaced by a time limit which is specified with the
 153     smtp_connection_reuse_time_limit parameter. In addition, Postfix 2.3 logs
 154     the use count of multiply-used connections, as shown in the following
 155     example:
 156
 157         Nov  3 16:04:31 myname postfix/smtp[30840]: 19B6B2900FE:
 158         to=<wietse@test.example.com>, orig_to=<wietse@test>,
 159         relay=mail.example.com[1.2.3.4], c\bco\bon\bnn\bn_\b_u\bus\bse\be=\b=2\b2, delay=0.22,
 160         delays=0.04/0.01/0.05/0.1, dsn=2.0.0, status=sent (250 2.0.0 Ok)
 161
 162   * The connection cache explicitly labels each cached connection with
 163     destination domain and IP address information. A connection cache lookup
 164     succeeds only when the correct information is specified. This prevents mis-
 165     delivery of mail.
 166
 167 C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhe\be l\bli\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
 168
 169 Postfix SMTP connection caching conflicts with certain applications:
 170
 171   * The Postfix shared connection cache cannot be used with TLS, because saved
 172     TLS session information can be used only when a new connection is created
 173     (this limitation does not exist in connection caching implementations that
 174     reuse a connection only in the process that creates it). For this reason,
 175     the Postfix smtp(8) client always closes the connection after completing an
 176     attempt to deliver mail over TLS.
 177
 178   * Postfix connection caching currently does not support multiple SASL
 179     accounts per mail server. Specifically, Postfix connection caching assumes
 180     that a SASL credential is valid for all hostnames or domain names that
 181     deliver via the same mail server IP address and TCP port, and assume that
 182     the SASL credential does not depend on the message originator.
 183
 184 C\bCo\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhe\be s\bst\bta\bat\bti\bis\bst\bti\bic\bcs\bs
 185
 186 The scache(8) connection cache server logs statistics about the peak cache size
 187 and the cache hit rates. This information is logged every
 188 connection_cache_status_update_time seconds, when the process terminates after
 189 the maximal idle time is exceeded, or when Postfix is reloaded.
 190
 191   * Hit rates for connection cache lookups by domain will tell you how useful
 192     connection caching is.
 193
 194   * Connection cache lookups by network address will always fail, unless you're
 195     sending mail to different domains that share the same MX hosts.
 196
 197   * No statistics are logged when no attempts are made to access the connection
 198     cache.
 199