dist/proto/XFORWARD_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix XFORWARD Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix XFORWARD Howto</h1>

<hr>

<h2>Purpose of the XFORWARD extension to SMTP</h2>

<p> When an SMTP server announces support for the XFORWARD command,
an SMTP client may send information that overrides one or more
client-related logging attributes.  The XFORWARD command targets
the following problem: </p>

<ul>

    <li> <p> Logging after SMTP-based content filter. With the
    deployment of Internet-&gt;MTA1-&gt;filter-&gt;MTA2 style
    content filter applications, the logging of client and message
    identifying information changes when MTA1 gives the mail to
    the content filter.  To simplify the interpretation of MTA2
    logging, it would help if MTA1 could forward remote client
    and/or message identifying information through the content
    filter to MTA2, so that the information could be logged as part
    of mail handling transactions. </p>

</ul>

<p> This extension is implemented as a separate ESMTP command, and
can be used to transmit client or message attributes incrementally.
It is not implemented by passing additional parameters via the MAIL
FROM command, because doing so would require extending the MAIL
FROM command length limit by another 600 or more characters beyond
the space that is already needed to support other extensions such
as AUTH and DSN. </p>

<h2>XFORWARD Command syntax</h2>

<p> An example of a client-server conversation is given at the end
of this document.  </p>

<p> In SMTP server EHLO replies, the keyword associated with this
extension is XFORWARD. The keyword is followed by the names of the
attributes that the XFORWARD implementation supports. </p>

<p> After receiving the server's announcement for XFORWARD support,
the client may send XFORWARD requests at any time except in
the middle of a mail delivery transaction (i.e.  between MAIL and
RSET or DOT).  The command may be pipelined when the server supports
ESMTP command pipelining.  </p>

<p> The syntax of XFORWARD requests is described below.  Upper case
and quoted strings specify terminals, lowercase strings specify
meta terminals, and SP is whitespace.  Although command and attribute
names are shown in upper case, they are in fact case insensitive.
</p>

<blockquote>
<p>
    xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value )
</p>
<p>
    attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | IDENT | SOURCE )
</p>
<p>
    attribute-value = xtext
</p>
</blockquote>

<ul>

    <li> <p> Attribute values are xtext encoded as per RFC 1891.
    </p>

    <li> <p> The NAME attribute specifies the up-stream hostname,
    or [UNAVAILABLE] when the information is unavailable. The
    hostname may be a non-DNS hostname. </p>

    <li> <p> The ADDR attribute specifies the up-stream network
    address: a numerical IPv4 network address, an IPv6 address
    prefixed with IPV6:, or [UNAVAILABLE] when the address information
    is unavailable.  Address information is not enclosed with [].
    </p>

    <li> <p> The PORT attribute specifies an up-stream client TCP
    port number in decimal, or [UNAVAILABLE] when the information
    is unavailable.  </p>

    <li> <p> The PROTO attribute specifies the mail protocol for
    receiving mail from the up-stream host. This may be an SMTP or
    non-SMTP protocol name of up to 64 characters, or [UNAVAILABLE]
    when the information is unavailable. </p>

    <li> <p> The HELO attribute specifies the hostname that the
    up-stream host announced itself with (not necessarily via the
    SMTP HELO command), or [UNAVAILABLE] when the information is
    unavailable. The hostname may be a non-DNS hostname. </p>

    <li> <p> The IDENT attribute specifies a local message identifier
    on the up-stream host, or [UNAVAILABLE] when the information
    is unavailable. The down-stream MTA may log this information
    together with its own local message identifier to facilitate
    message tracking across MTAs. </p>

    <li> <p> The SOURCE attribute specifies LOCAL when the message
    was received from a source that is local with respect to the
    up-stream host (for example, the message originated from the
    up-stream host itself), REMOTE for all other mail, or [UNAVAILABLE]
    when the information is unavailable. The down-stream MTA may
    decide to enable features such as header munging or address
    qualification with mail from local sources but not other sources.
    </p>

</ul>

<p> Note 1: an attribute-value element must not be longer than
255 characters (specific attributes may impose shorter lengths).
After xtext decoding, attribute values must not contain control
characters, non-ASCII characters, whitespace, or other characters
that are special in message headers.  </p>

<p> Note 2: DNS hostnames can be up to 255 characters long. The
XFORWARD client implementation must not send XFORWARD commands that
exceed the 512 character limit for SMTP commands. </p>

<p> Note 3: [UNAVAILABLE] may be specified in upper case, lower
case or mixed case. </p>

<p> Note 4: Postfix implementations prior to version 2.3 do not
xtext encode attribute values. Servers that wish to interoperate
with these older implementations should be prepared to receive
unencoded information. </p>

<h2> XFORWARD Server operation </h2>

<p> The server maintains a set of XFORWARD attributes with forwarded
information, in addition the current SMTP session attributes.
Normally, all XFORWARD attributes are in the undefined state, and
the server uses the current SMTP session attributes for logging
purposes. </p>

<p> Upon receipt of an initial XFORWARD command, the SMTP server
initializes all XFORWARD attributes to [UNAVAILABLE].  With each
valid XFORWARD command, the server updates XFORWARD attributes with
the specified values. </p>

<p> The server must not mix client attributes from XFORWARD with
client attributes from the current SMTP session. </p>

<p> At the end of each MAIL FROM transaction (i.e. RSET or DOT),
the server resets all XFORWARD attributes to the undefined state,
and is ready to receive another initial XFORWARD command.  </p>

<h2> XFORWARD Server reply codes </h2>

<blockquote>

<table bgcolor="#f0f0ff" border="1">

<tr> <th> Code </th> <th> Meaning </th> </tr>

<tr> <td> 250 </td> <td> success  </td> </tr>

<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr>

<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr>

<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr>

<tr> <td> 550 </td> <td> insufficient authorization </td> </tr>

</table>

</blockquote>

<h2>XFORWARD Example</h2>

<p> In the following example, information sent by the client is
shown in bold font. </p>

<blockquote>
<pre>
220 server.example.com ESMTP Postfix
<b>EHLO client.example.com</b>
250-server.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-XFORWARD NAME ADDR PROTO HELO
250 8BITMIME
<b>XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b>
250 Ok
<b>XFORWARD HELO=spike.porcupine.org</b>
250 Ok
<b>MAIL FROM:&lt;wietse@porcupine.org&gt;</b>
250 Ok
<b>RCPT TO:&lt;user@example.com&gt;</b>
250 Ok
<b>DATA</b>
354 End data with &lt;CR&gt;&lt;LF&gt;.&lt;CR&gt;&lt;LF&gt;
<b>. . .<i>message content</i>. . .</b>
<b>.</b>
250 Ok: queued as 3CF6B2AAE8
<b>QUIT</b>
221 Bye
</pre>
</blockquote>

<h2>Security</h2>

<p> The XFORWARD command changes audit trails.  Use of this command
must be restricted to authorized clients. </p>

<h2>SMTP connection caching</h2>

<p> SMTP connection caching makes it possible to deliver multiple
messages within the same SMTP session. The XFORWARD attributes are
reset after the MAIL FROM transaction completes (after RSET or DOT),
so there is no risk of information leakage. </p>

<h2> References </h2>

<p> Moore, K, "SMTP Service Extension for Delivery Status Notifications",
RFC 1891, January 1996. </p>

</body>

</html>