diff options
Diffstat (limited to 'proto/XFORWARD_README.html')
| -rw-r--r-- | proto/XFORWARD_README.html | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/proto/XFORWARD_README.html b/proto/XFORWARD_README.html new file mode 100644 index 0000000..ad380a4 --- /dev/null +++ b/proto/XFORWARD_README.html @@ -0,0 +1,242 @@ +<!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=utf-8"> +<link rel='stylesheet' type='text/css' href='postfix-doc.css'> + +</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->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 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:<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 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> |