summaryrefslogtreecommitdiffstats
path: root/proto/XFORWARD_README.html
diff options
context:
space:
mode:
Diffstat (limited to 'proto/XFORWARD_README.html')
-rw-r--r--proto/XFORWARD_README.html241
1 files changed, 241 insertions, 0 deletions
diff --git a/proto/XFORWARD_README.html b/proto/XFORWARD_README.html
new file mode 100644
index 0000000..18cef6c
--- /dev/null
+++ b/proto/XFORWARD_README.html
@@ -0,0 +1,241 @@
+<!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>