external/ibm-public/postfix/dist/html/XFORWARD_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 XFORWARD 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 XFORWARD Howto</h1>
  17
  18 <hr>
  19
  20 <h2>Purpose of the XFORWARD extension to SMTP</h2>
  21
  22 <p> When an SMTP server announces support for the XFORWARD command,
  23 an SMTP client may send information that overrides one or more
  24 client-related logging attributes.  The XFORWARD command targets
  25 the following problem: </p>
  26
  27 <ul>
  28
  29     <li> <p> Logging after SMTP-based content filter. With the
  30     deployment of Internet-&gt;MTA1-&gt;filter-&gt;MTA2 style
  31     content filter applications, the logging of client and message
  32     identifying information changes when MTA1 gives the mail to
  33     the content filter.  To simplify the interpretation of MTA2
  34     logging, it would help if MTA1 could forward remote client
  35     and/or message identifying information through the content
  36     filter to MTA2, so that the information could be logged as part
  37     of mail handling transactions. </p>
  38
  39 </ul>
  40
  41 <p> This extension is implemented as a separate EMSTP command, and
  42 can be used to transmit client or message attributes incrementally.
  43 It is not implemented by passing additional parameters via the MAIL
  44 FROM command, because doing so would require extending the MAIL
  45 FROM command length limit by another 600 or more characters beyond
  46 the space that is already needed to support other extensions such
  47 as AUTH and DSN. </p>
  48
  49 <h2>XFORWARD Command syntax</h2>
  50
  51 <p> An example of a client-server conversation is given at the end
  52 of this document.  </p>
  53
  54 <p> In SMTP server EHLO replies, the keyword associated with this
  55 extension is XFORWARD. The keyword is followed by the names of the
  56 attributes that the XFORWARD implementation supports. </p>
  57
  58 <p> After receiving the server's announcement for XFORWARD support,
  59 the client may send XFORWARD requests at any time except in
  60 the middle of a mail delivery transaction (i.e.  between MAIL and
  61 RSET or DOT).  The command may be pipelined when the server supports
  62 ESMTP command pipelining.  </p>
  63
  64 <p> The syntax of XFORWARD requests is described below.  Upper case
  65 and quoted strings specify terminals, lowercase strings specify
  66 meta terminals, and SP is whitespace.  Although command and attribute
  67 names are shown in upper case, they are in fact case insensitive.
  68 </p>
  69
  70 <blockquote>
  71 <p>
  72     xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value )
  73 </p>
  74 <p>
  75     attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | SOURCE )
  76 </p>
  77 <p>
  78     attribute-value = xtext
  79 </p>
  80 </blockquote>
  81
  82 <ul>
  83
  84     <li> <p> Attribute values are xtext encoded as per <a href="http://tools.ietf.org/html/rfc1891">RFC 1891</a>.
  85     </p>
  86
  87     <li> <p> The NAME attribute specifies the up-stream hostname,
  88     or [UNAVAILABLE] when the information is unavailable. The
  89     hostname may be a non-DNS hostname. </p>
  90
  91     <li> <p> The ADDR attribute specifies the up-stream network
  92     address: a numerical IPv4 network address, an IPv6 address
  93     prefixed with IPV6:, or [UNAVAILABLE] when the address information
  94     is unavailable.  Address information is not enclosed with [].
  95     </p>
  96
  97     <li> <p> The PORT attribute specifies an up-stream client TCP
  98     port number in decimal, or [UNAVAILABLE] when the information
  99     is unavailable.  </p>
 100
 101     <li> <p> The PROTO attribute specifies the mail protocol for
 102     receiving mail from the up-stream host. This may be an SMTP or
 103     non-SMTP protocol name of up to 64 characters, or [UNAVAILABLE]
 104     when the information is unavailable. </p>
 105
 106     <li> <p> The HELO attribute specifies the hostname that the
 107     up-stream host announced itself with (not necessarily via the
 108     SMTP HELO command), or [UNAVAILABLE] when the information is
 109     unavailable. The hostname may be a non-DNS hostname. </p>
 110
 111     <li> <p> The SOURCE attribute specifies LOCAL when the message
 112     was received from a source that is local with respect to the
 113     up-stream host (for example, the message originated from the
 114     up-stream host itself), REMOTE for all other mail, or [UNAVAILABLE]
 115     when the information is unavailable. The down-stream MTA may
 116     decide to enable features such as header munging or address
 117     qualification with mail from local sources but not other sources.
 118     </p>
 119
 120 </ul>
 121
 122 <p> Note 1: an attribute-value element must not be longer than
 123 255 characters (specific attributes may impose shorter lengths).
 124 After xtext decoding, attribute values must not contain control
 125 characters, non-ASCII characters, whitespace, or other characters
 126 that are special in message headers.  </p>
 127
 128 <p> Note 2: DNS hostnames can be up to 255 characters long. The
 129 XFORWARD client implementation must not send XFORWARD commands that
 130 exceed the 512 character limit for SMTP commands. </p>
 131
 132 <p> Note 3: [UNAVAILABLE] may be specified in upper case, lower
 133 case or mixed case. </p>
 134
 135 <p> Note 4: Postfix implementations prior to version 2.3 do not
 136 xtext encode attribute values. Servers that wish to interoperate
 137 with these older implementations should be prepared to receive
 138 unencoded information. </p>
 139
 140 <h2> XFORWARD Server operation </h2>
 141
 142 <p> The server maintains a set of XFORWARD attributes with forwarded
 143 information, in addition the current SMTP session attributes.
 144 Normally, all XFORWARD attributes are in the undefined state, and
 145 the server uses the current SMTP session attributes for logging
 146 purposes. </p>
 147
 148 <p> Upon receipt of an initial XFORWARD command, the SMTP server
 149 initializes all XFORWARD attributes to [UNAVAILABLE].  With each
 150 valid XFORWARD command, the server updates XFORWARD attributes with
 151 the specified values. </p>
 152
 153 <p> The server must not mix client attributes from XFORWARD with
 154 client attributes from the current SMTP session. </p>
 155
 156 <p> At the end of each MAIL FROM transaction (i.e. RSET or DOT),
 157 the server resets all XFORWARD attributes to the undefined state,
 158 and is ready to receive another initial XFORWARD command.  </p>
 159
 160 <h2> XFORWARD Server reply codes </h2>
 161
 162 <blockquote>
 163
 164 <table bgcolor="#f0f0ff" border="1">
 165
 166 <tr> <th> Code </th> <th> Meaning </th> </tr>
 167
 168 <tr> <td> 250 </td> <td> success  </td> </tr>
 169
 170 <tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr>
 171
 172 <tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr>
 173
 174 <tr> <td> 503 </td> <td> mail transaction in progress </td> </tr>
 175
 176 <tr> <td> 550 </td> <td> insufficient authorization </td> </tr>
 177
 178 </table>
 179
 180 </blockquote>
 181
 182 <h2>XFORWARD Example</h2>
 183
 184 <p> In the following example, information sent by the client is
 185 shown in bold font. </p>
 186
 187 <blockquote>
 188 <pre>
 189 220 server.example.com ESMTP Postfix
 190 <b>EHLO client.example.com</b>
 191 250-server.example.com
 192 250-PIPELINING
 193 250-SIZE 10240000
 194 250-VRFY
 195 250-ETRN
 196 250-XFORWARD NAME ADDR PROTO HELO
 197 250 8BITMIME
 198 <b>XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b>
 199 250 Ok
 200 <b>XFORWARD HELO=spike.porcupine.org</b>
 201 250 Ok
 202 <b>MAIL FROM:&lt;wietse@porcupine.org&gt;</b>
 203 250 Ok
 204 <b>RCPT TO:&lt;user@example.com&gt;</b>
 205 250 Ok
 206 <b>DATA</b>
 207 354 End data with &lt;CR&gt;&lt;LF&gt;.&lt;CR&gt;&lt;LF&gt;
 208 <b>. . .<i>message content</i>. . .</b>
 209 <b>.</b>
 210 250 Ok: queued as 3CF6B2AAE8
 211 <b>QUIT</b>
 212 221 Bye
 213 </pre>
 214 </blockquote>
 215
 216 <h2>Security</h2>
 217
 218 <p> The XFORWARD command changes audit trails.  Use of this command
 219 must be restricted to authorized clients. </p>
 220
 221 <h2>SMTP connection caching</h2>
 222
 223 <p> SMTP connection caching makes it possible to deliver multiple
 224 messages within the same SMTP session. The XFORWARD attributes are
 225 reset after the MAIL FROM transaction completes (after RSET or DOT),
 226 so there is no risk of information leakage. </p>
 227
 228 <h2> References </h2>
 229
 230 <p> Moore, K, "SMTP Service Extension for Delivery Status Notifications",
 231 <a href="http://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
 232
 233 </body>
 234
 235 </html>