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, 23an SMTP client may send information that overrides one or more 24client-related logging attributes. The XFORWARD command targets 25the following problem: </p> 26 27<ul> 28 29 <li> <p> Logging after SMTP-based content filter. With the 30 deployment of Internet->MTA1->filter->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 EMSTP command, and 42can be used to transmit client or message attributes incrementally. 43It is not implemented by passing additional parameters via the MAIL 44FROM command, because doing so would require extending the MAIL 45FROM command length limit by another 600 or more characters beyond 46the space that is already needed to support other extensions such 47as 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 52of this document. </p> 53 54<p> In SMTP server EHLO replies, the keyword associated with this 55extension is XFORWARD. The keyword is followed by the names of the 56attributes that the XFORWARD implementation supports. </p> 57 58<p> After receiving the server's announcement for XFORWARD support, 59the client may send XFORWARD requests at any time except in 60the middle of a mail delivery transaction (i.e. between MAIL and 61RSET or DOT). The command may be pipelined when the server supports 62ESMTP command pipelining. </p> 63 64<p> The syntax of XFORWARD requests is described below. Upper case 65and quoted strings specify terminals, lowercase strings specify 66meta terminals, and SP is whitespace. Although command and attribute 67names 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 | 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 RFC 1891. 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 SOURCE attribute specifies LOCAL when the message 112 was received from a source that is local with respect to the 113 up-stream host (for example, the message originated from the 114 up-stream host itself), REMOTE for all other mail, or [UNAVAILABLE] 115 when the information is unavailable. The down-stream MTA may 116 decide to enable features such as header munging or address 117 qualification with mail from local sources but not other sources. 118 </p> 119 120</ul> 121 122<p> Note 1: an attribute-value element must not be longer than 123255 characters (specific attributes may impose shorter lengths). 124After xtext decoding, attribute values must not contain control 125characters, non-ASCII characters, whitespace, or other characters 126that are special in message headers. </p> 127 128<p> Note 2: DNS hostnames can be up to 255 characters long. The 129XFORWARD client implementation must not send XFORWARD commands that 130exceed the 512 character limit for SMTP commands. </p> 131 132<p> Note 3: [UNAVAILABLE] may be specified in upper case, lower 133case or mixed case. </p> 134 135<p> Note 4: Postfix implementations prior to version 2.3 do not 136xtext encode attribute values. Servers that wish to interoperate 137with these older implementations should be prepared to receive 138unencoded information. </p> 139 140<h2> XFORWARD Server operation </h2> 141 142<p> The server maintains a set of XFORWARD attributes with forwarded 143information, in addition the current SMTP session attributes. 144Normally, all XFORWARD attributes are in the undefined state, and 145the server uses the current SMTP session attributes for logging 146purposes. </p> 147 148<p> Upon receipt of an initial XFORWARD command, the SMTP server 149initializes all XFORWARD attributes to [UNAVAILABLE]. With each 150valid XFORWARD command, the server updates XFORWARD attributes with 151the specified values. </p> 152 153<p> The server must not mix client attributes from XFORWARD with 154client attributes from the current SMTP session. </p> 155 156<p> At the end of each MAIL FROM transaction (i.e. RSET or DOT), 157the server resets all XFORWARD attributes to the undefined state, 158and is ready to receive another initial XFORWARD command. </p> 159 160<h2> XFORWARD Server reply codes </h2> 161 162<blockquote> 163 164<table bgcolor="#f0f0ff" border="1"> 165 166<tr> <th> Code </th> <th> Meaning </th> </tr> 167 168<tr> <td> 250 </td> <td> success </td> </tr> 169 170<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr> 171 172<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr> 173 174<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr> 175 176<tr> <td> 550 </td> <td> insufficient authorization </td> </tr> 177 178</table> 179 180</blockquote> 181 182<h2>XFORWARD Example</h2> 183 184<p> In the following example, information sent by the client is 185shown in bold font. </p> 186 187<blockquote> 188<pre> 189220 server.example.com ESMTP Postfix 190<b>EHLO client.example.com</b> 191250-server.example.com 192250-PIPELINING 193250-SIZE 10240000 194250-VRFY 195250-ETRN 196250-XFORWARD NAME ADDR PROTO HELO 197250 8BITMIME 198<b>XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b> 199250 Ok 200<b>XFORWARD HELO=spike.porcupine.org</b> 201250 Ok 202<b>MAIL FROM:<wietse@porcupine.org></b> 203250 Ok 204<b>RCPT TO:<user@example.com></b> 205250 Ok 206<b>DATA</b> 207354 End data with <CR><LF>.<CR><LF> 208<b>. . .<i>message content</i>. . .</b> 209<b>.</b> 210250 Ok: queued as 3CF6B2AAE8 211<b>QUIT</b> 212221 Bye 213</pre> 214</blockquote> 215 216<h2>Security</h2> 217 218<p> The XFORWARD command changes audit trails. Use of this command 219must be restricted to authorized clients. </p> 220 221<h2>SMTP connection caching</h2> 222 223<p> SMTP connection caching makes it possible to deliver multiple 224messages within the same SMTP session. The XFORWARD attributes are 225reset after the MAIL FROM transaction completes (after RSET or DOT), 226so there is no risk of information leakage. </p> 227 228<h2> References </h2> 229 230<p> Moore, K, "SMTP Service Extension for Delivery Status Notifications", 231RFC 1891, January 1996. </p> 232 233</body> 234 235</html> 236