postfix-master/CONNECTION_CACHE_README.html

   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 Connection Cache </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 Connection Cache </h1>
  17
  18 <hr>
  19
  20 <h2>Introduction</h2>
  21
  22 <p> This document describes the Postfix connection cache implementation,
  23 which is available with Postfix version 2.2 and later. </p>
  24
  25 <p> Topics covered in this document: </p>
  26
  27 <ul>
  28
  29 <li><a href="#summary"> What SMTP connection caching can do for you</a>
  30
  31 <li><a href="#implementation"> Connection cache implementation</a>
  32
  33 <li><a href="#configuration"> Connection cache configuration</a>
  34
  35 <li><a href="#safety">Connection cache safety mechanisms </a>
  36
  37 <li><a href="#limitations">Connection cache limitations</a>
  38
  39 <li><a href="#statistics">Connection cache statistics</a>
  40
  41 </ul>
  42
  43 <h2><a name="summary">What SMTP connection caching can do for
  44 you</a></h2>
  45
  46 <p> With SMTP connection caching, Postfix can deliver multiple
  47 messages over the same SMTP connection. By default, Postfix 2.2
  48 reuses an SMTP connection automatically when a destination has
  49 high volume of mail in the <a href="QSHAPE_README.html#active_queue">active queue</a>.  </p>
  50
  51 <p> SMTP Connection caching is a performance feature. Whether or not
  52 it actually improves performance depends on the conditions: </p>
  53
  54 <ul>
  55
  56 <li> <p> SMTP Connection caching can greatly improve performance
  57 when delivering mail to a destination with multiple mail servers,
  58 because it can help Postfix to skip over a non-responding server.
  59 </p>
  60
  61 <li> <p> Otherwise, the benefits of SMTP connection caching are
  62 minor: it eliminates the latency of the TCP handshake (SYN, SYN+ACK,
  63 ACK), plus the latency of the SMTP initial handshake (220 greeting,
  64 EHLO command, EHLO response).
  65
  66 <li> <p> SMTP Connection caching gives no gains with respect to
  67 SMTP session tear-down.  The Postfix <a href="smtp.8.html">smtp(8)</a> client normally does
  68 not wait for the server's reply to the QUIT command, and it never
  69 waits for the TCP final handshake to complete.  </p>
  70
  71 <li> <p> SMTP Connection caching introduces some overhead: the
  72 client needs to send an RSET command to find out if a connection
  73 is still usable, before it can send the next MAIL FROM command.
  74 </p>
  75
  76 </ul>
  77
  78 <p> For other potential issues with SMTP connection caching, see
  79 the discussion of <a href="#limitations">limitations</a> at the end
  80 of this document. </p>
  81
  82 <h2><a name="implementation">Connection cache implementation</a></h2>
  83
  84 <p> For an overview of how Postfix delivers mail, see the Postfix
  85 architecture <a href="OVERVIEW.html">OVERVIEW</a> document. </p>
  86
  87 <p> The Postfix connection cache is shared among Postfix mail
  88 delivering processes.  This maximizes the opportunity to reuse an
  89 open connection.  Other MTAs such as Sendmail or exim have a
  90 non-shared connection cache. Here, a connection can be reused only
  91 by the mail delivering process that creates the connection.  To get
  92 the same performance improvement as with a shared connection cache,
  93 non-shared connections need to be kept open for a longer time. </p>
  94
  95 <p> The <a href="scache.8.html">scache(8)</a> server, introduced with Postfix version 2.2,
  96 maintains the shared connection cache.  With Postfix version 2.2,
  97 only the <a href="smtp.8.html">smtp(8)</a> client has support to access this cache.  </p>
  98
  99 <blockquote>
 100
 101 <table>
 102
 103 <tr> <td> </td> <td> <tt> /-- </tt> </td> <td align="center"
 104 colspan="3" bgcolor="#f0f0ff"> <a href="smtp.8.html">smtp(8)</a> </td> <td colspan="2"> <tt>
 105 --&gt; </tt> Internet </td> </tr>
 106
 107 <tr> <td align="center" bgcolor="#f0f0ff"> <a href="qmgr.8.html">qmgr(8)</a> </td> <td> </td>
 108 <td align="center" rowspan="3"> &nbsp; </td> <td align="center"
 109 rowspan="3"><tt>|<br>|<br>|<br>|<br>v</tt></td> <td> &nbsp; </td>
 110 </tr>
 111
 112 <tr> <td> </td> <td> <tt> \-- </tt> </td> <td align="center"
 113 colspan="2" bgcolor="#f0f0ff"> <a href="smtp.8.html">smtp(8)</a> </td> <td align="left"> <tt>
 114 --&gt; </tt> Internet </td> </tr>
 115
 116 <tr> <td colspan="3"> </td> <td align="center"><tt>^<br>|</tt></td>
 117 <td> &nbsp; </td> </tr>
 118
 119 <tr> <td colspan="3"> </td> <td align="center" colspan="3"
 120 bgcolor="#f0f0ff"> <a href="scache.8.html">scache(8)</a> </td> </tr>
 121
 122 </table>
 123
 124 </blockquote>
 125
 126 <p> When SMTP connection caching is enabled (see next section), the
 127 <a href="smtp.8.html">smtp(8)</a> client does not disconnect after a mail transaction, but
 128 gives the connection to the <a href="scache.8.html">scache(8)</a> server which keeps the
 129 connection open for a limited amount of time. </p>
 130
 131 <p> After handing over the open connection to the <a href="scache.8.html">scache(8)</a> server,
 132 the <a href="smtp.8.html">smtp(8)</a> client continues with some other mail delivery request.
 133 Meanwhile, any <a href="smtp.8.html">smtp(8)</a> client process can ask the <a href="scache.8.html">scache(8)</a> server
 134 for that cached connection and reuse it for mail delivery.  </p>
 135
 136 <p> The connection cache can be searched by destination domain name
 137 (the right-hand side of the recipient address) and by the IP address
 138 of the host at the other end of the connection. This allows Postfix
 139 to reuse a connection even when the remote host is mail server for
 140 domains with different names.  </p>
 141
 142 <h2><a name="configuration">Connection cache configuration </a></h2>
 143
 144 <p> The Postfix <a href="smtp.8.html">smtp(8)</a> client supports two connection caching
 145 strategies: </p>
 146
 147 <ul>
 148
 149 <li> <p> On-demand connection caching. This is enabled by default,
 150 and is controlled with the <a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> configuration
 151 parameter.  When this feature is enabled, the Postfix <a href="smtp.8.html">smtp(8)</a> client
 152 automatically saves a connection to the connection cache when a
 153 destination has a high volume of mail in the <a href="QSHAPE_README.html#active_queue">active queue</a>.  </p>
 154
 155 <p> Example: </p>
 156
 157 <blockquote>
 158
 159 <pre>
 160 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 161     <a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> = yes
 162 </pre>
 163
 164 </blockquote>
 165
 166 <li> <p> Per-destination connection caching. This is enabled by
 167 explicitly listing specific destinations with the
 168 <a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> configuration parameter. After
 169 completing delivery to a selected destination, the Postfix <a href="smtp.8.html">smtp(8)</a>
 170 client <i>always</i> saves the connection to the connection cache.
 171 </p>
 172
 173 <p> Specify a comma or white space separated list of destinations
 174 or pseudo-destinations: </p>
 175
 176 <ul>
 177
 178 <li> <p> if mail is sent without a <a href="postconf.5.html#relayhost">relay host</a>: a domain name (the
 179 right-hand side of an email address, without the [] around a numeric
 180 IP address), </p>
 181
 182 <li> <p> if mail is sent via a <a href="postconf.5.html#relayhost">relay host</a>: a <a href="postconf.5.html#relayhost">relay host</a> name (without
 183 the [] or non-default TCP port), as specified in <a href="postconf.5.html">main.cf</a> or in the
 184 transport map, </p>
 185
 186 <li> <p> a /file/name with domain names and/or <a href="postconf.5.html#relayhost">relay host</a> names as
 187 defined above, </p>
 188
 189 <li> <p> a "<a href="DATABASE_README.html">type:table</a>" with domain names and/or <a href="postconf.5.html#relayhost">relay host</a> names
 190 on the left-hand side. The right-hand side result from "<a href="DATABASE_README.html">type:table</a>"
 191 lookups is ignored.  </p>
 192
 193 </ul>
 194
 195 <p> Examples: </p>
 196
 197 <blockquote>
 198
 199 <pre>
 200 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 201     <a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> = $<a href="postconf.5.html#relayhost">relayhost</a>
 202     <a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> = hotmail.com, ...
 203     <a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> = static:all (<i>not recommended</i>)
 204 </pre>
 205
 206 </blockquote>
 207
 208 </ul>
 209
 210 <h2><a name="safety">Connection cache safety mechanisms </a></h2>
 211
 212 <p> Connection caching must be used wisely. It is anti-social to
 213 keep an unused SMTP connection open for a significant amount of
 214 time, and it is unwise to send huge numbers of messages through
 215 the same connection. In order to avoid problems with SMTP connection
 216 caching, Postfix implements the following safety mechanisms: </p>
 217
 218 <ul>
 219
 220 <li> <p> The Postfix <a href="scache.8.html">scache(8)</a> server keeps a connection open for
 221 only a limited time. The time limit is specified with the
 222 <a href="postconf.5.html#smtp_connection_cache_time_limit">smtp_connection_cache_time_limit</a> and with the <a href="postconf.5.html#connection_cache_ttl_limit">connection_cache_ttl_limit</a>
 223 configuration parameters. This prevents anti-social behavior. </p>
 224
 225 <li> <p> The Postfix <a href="smtp.8.html">smtp(8)</a> client reuses a session for only a
 226 limited number of times. This avoids triggering bugs in implementations
 227 that do not correctly handle multiple deliveries per session. </p>
 228
 229 <p> With Postfix 2.2 the use count is limited with the
 230 <a href="postconf.5.html#smtp_connection_cache_reuse_limit">smtp_connection_cache_reuse_limit</a> configuration parameter. With
 231 Postfix 2.3 this is replaced by a time limit which is specified
 232 with the <a href="postconf.5.html#smtp_connection_reuse_time_limit">smtp_connection_reuse_time_limit</a> parameter. In addition,
 233 Postfix 2.3 logs the use count of multiply-used connections,
 234 as shown in the following example: </p>
 235
 236 <blockquote>
 237 <pre>
 238 Nov  3 16:04:31 myname postfix/smtp[30840]: 19B6B2900FE:
 239 to=&lt;wietse@test.example.com&gt;, orig_to=&lt;wietse@test&gt;,
 240 relay=mail.example.com[1.2.3.4], <b>conn_use=2</b>, delay=0.22,
 241 delays=0.04/0.01/0.05/0.1, dsn=2.0.0, status=sent (250 2.0.0 Ok)
 242 </pre>
 243 </blockquote>
 244
 245 <li> <p> The connection cache explicitly labels each cached connection
 246 with destination domain and IP address information.  A connection
 247 cache lookup succeeds only when the correct information is specified.
 248 This prevents mis-delivery of mail. </p>
 249
 250 </ul>
 251
 252 <h2><a name="limitations">Connection cache limitations</a></h2>
 253
 254 <p> Postfix SMTP connection caching conflicts with certain applications:
 255 </p>
 256
 257 <ul>
 258
 259 <li> <p> The Postfix shared connection cache cannot be used with
 260 TLS, because saved TLS session information can be used only when a
 261 new connection is created (this limitation does not exist in
 262 connection caching implementations that reuse a connection only in
 263 the process that creates it).  For this reason, the Postfix <a href="smtp.8.html">smtp(8)</a>
 264 client always closes the connection after completing an attempt to
 265 deliver mail over TLS.  </p>
 266
 267 <li> <p> Postfix connection caching currently does not support
 268 multiple SASL accounts per mail server.  Specifically, Postfix
 269 connection caching assumes that a SASL credential is valid for all
 270 hostnames or domain names that deliver via the same mail server IP
 271 address and TCP port, and assumes that the SASL credential does not
 272 depend on the message originator.  </p>
 273
 274 </ul>
 275
 276
 277 <h2><a name="statistics">Connection cache statistics </a></h2>
 278
 279 <p> The <a href="scache.8.html">scache(8)</a> connection cache server logs statistics about the
 280 peak cache size and the cache hit rates. This information is logged
 281 every <a href="postconf.5.html#connection_cache_status_update_time">connection_cache_status_update_time</a> seconds, when the process
 282 terminates after the maximal idle time is exceeded, or when Postfix
 283 is reloaded. </p>
 284
 285 <ul>
 286
 287 <li> <p> Hit rates for connection cache lookups by domain will tell
 288 you how useful connection caching is. </p>
 289
 290 <li> <p> Connection cache lookups by network address will always
 291 fail, unless you're sending mail to different domains that share
 292 the same MX hosts. </p>
 293
 294 <li> <p> No statistics are logged when no attempts are made to
 295 access the connection cache. </p>
 296
 297 </ul>
 298
 299
 300 </body>
 301
 302 </html>