postfix-master/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 ESMTP 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 | IDENT | 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 IDENT attribute specifies a local message identifier
 112     on the up-stream host, or [UNAVAILABLE] when the information
 113     is unavailable. The down-stream MTA may log this information
 114     together with its own local message identifier to facilitate
 115     message tracking across MTAs. </p>
 116
 117     <li> <p> The SOURCE attribute specifies LOCAL when the message
 118     was received from a source that is local with respect to the
 119     up-stream host (for example, the message originated from the
 120     up-stream host itself), REMOTE for all other mail, or [UNAVAILABLE]
 121     when the information is unavailable. The down-stream MTA may
 122     decide to enable features such as header munging or address
 123     qualification with mail from local sources but not other sources.
 124     </p>
 125
 126 </ul>
 127
 128 <p> Note 1: an attribute-value element must not be longer than
 129 255 characters (specific attributes may impose shorter lengths).
 130 After xtext decoding, attribute values must not contain control
 131 characters, non-ASCII characters, whitespace, or other characters
 132 that are special in message headers.  </p>
 133
 134 <p> Note 2: DNS hostnames can be up to 255 characters long. The
 135 XFORWARD client implementation must not send XFORWARD commands that
 136 exceed the 512 character limit for SMTP commands. </p>
 137
 138 <p> Note 3: [UNAVAILABLE] may be specified in upper case, lower
 139 case or mixed case. </p>
 140
 141 <p> Note 4: Postfix implementations prior to version 2.3 do not
 142 xtext encode attribute values. Servers that wish to interoperate
 143 with these older implementations should be prepared to receive
 144 unencoded information. </p>
 145
 146 <h2> XFORWARD Server operation </h2>
 147
 148 <p> The server maintains a set of XFORWARD attributes with forwarded
 149 information, in addition the current SMTP session attributes.
 150 Normally, all XFORWARD attributes are in the undefined state, and
 151 the server uses the current SMTP session attributes for logging
 152 purposes. </p>
 153
 154 <p> Upon receipt of an initial XFORWARD command, the SMTP server
 155 initializes all XFORWARD attributes to [UNAVAILABLE].  With each
 156 valid XFORWARD command, the server updates XFORWARD attributes with
 157 the specified values. </p>
 158
 159 <p> The server must not mix client attributes from XFORWARD with
 160 client attributes from the current SMTP session. </p>
 161
 162 <p> At the end of each MAIL FROM transaction (i.e. RSET or DOT),
 163 the server resets all XFORWARD attributes to the undefined state,
 164 and is ready to receive another initial XFORWARD command.  </p>
 165
 166 <h2> XFORWARD Server reply codes </h2>
 167
 168 <blockquote>
 169
 170 <table bgcolor="#f0f0ff" border="1">
 171
 172 <tr> <th> Code </th> <th> Meaning </th> </tr>
 173
 174 <tr> <td> 250 </td> <td> success  </td> </tr>
 175
 176 <tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr>
 177
 178 <tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr>
 179
 180 <tr> <td> 503 </td> <td> mail transaction in progress </td> </tr>
 181
 182 <tr> <td> 550 </td> <td> insufficient authorization </td> </tr>
 183
 184 </table>
 185
 186 </blockquote>
 187
 188 <h2>XFORWARD Example</h2>
 189
 190 <p> In the following example, information sent by the client is
 191 shown in bold font. </p>
 192
 193 <blockquote>
 194 <pre>
 195 220 server.example.com ESMTP Postfix
 196 <b>EHLO client.example.com</b>
 197 250-server.example.com
 198 250-PIPELINING
 199 250-SIZE 10240000
 200 250-VRFY
 201 250-ETRN
 202 250-XFORWARD NAME ADDR PROTO HELO
 203 250 8BITMIME
 204 <b>XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b>
 205 250 Ok
 206 <b>XFORWARD HELO=spike.porcupine.org</b>
 207 250 Ok
 208 <b>MAIL FROM:&lt;wietse@porcupine.org&gt;</b>
 209 250 Ok
 210 <b>RCPT TO:&lt;user@example.com&gt;</b>
 211 250 Ok
 212 <b>DATA</b>
 213 354 End data with &lt;CR&gt;&lt;LF&gt;.&lt;CR&gt;&lt;LF&gt;
 214 <b>. . .<i>message content</i>. . .</b>
 215 <b>.</b>
 216 250 Ok: queued as 3CF6B2AAE8
 217 <b>QUIT</b>
 218 221 Bye
 219 </pre>
 220 </blockquote>
 221
 222 <h2>Security</h2>
 223
 224 <p> The XFORWARD command changes audit trails.  Use of this command
 225 must be restricted to authorized clients. </p>
 226
 227 <h2>SMTP connection caching</h2>
 228
 229 <p> SMTP connection caching makes it possible to deliver multiple
 230 messages within the same SMTP session. The XFORWARD attributes are
 231 reset after the MAIL FROM transaction completes (after RSET or DOT),
 232 so there is no risk of information leakage. </p>
 233
 234 <h2> References </h2>
 235
 236 <p> Moore, K, "SMTP Service Extension for Delivery Status Notifications",
 237 <a href="http://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
 238
 239 </body>
 240
 241 </html>