XFORWARD_README.html [plain text]
<!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> The XFORWARD command targets the following problem: </p>
<ul>
<li> <p> Logging after SMTP-based content filter. With the
deployment of Internet->MTA1->filter->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 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 in order to support other extensions
such as AUTH. </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> The client may send the XFORWARD request at any time except in
the middle of a mail delivery transaction (i.e. between MAIL and
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 | PROTO | HELO )
</p>
</blockquote>
<ul>
<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, or [UNAVAILABLE] when the information is unavailable.
Address information is not enclosed with []. The address may
be a non-IP address. </p>
<li> <p> The PROTO attribute specifies the mail protocol for
receiving mail from the up-stream host. This may be an SMTP
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>
</ul>
<p> Note 1: Attribute values must not be longer than 255 characters
(specific attributes may impose shorter lengths), must not contain
control characters, non-ASCII characters, whitespace, or other
characters that are special in message headers. Future attributes
that may violate this should use xtext encoding as described in
RFC 1891. </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: the XFORWARD server implementation must not mix
information from the current SMTP session with forwarded information
from an up-stream session. </p>
<p> The XFORWARD server reply codes are as follows: </p>
<blockquote>
<table bgcolor="#f0f0ff" border="1">
<tr> <th> Code </th> <th> Meaning </th> </tr>
<tr> <td> 250 </td> <td> success </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> 421 </td> <td> unable to proceed, disconnecting </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:<wietse@porcupine.org></b>
250 Ok
<b>RCPT TO:<user@example.com></b>
250 Ok
<b>DATA</b>
354 End data with <CR><LF>.<CR><LF>
<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 command completes, so there is no risk
of information leakage. </p>
</body>
</html>