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=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix XFORWARD Howto</h1> 18 19<hr> 20 21<h2>Purpose of the XFORWARD extension to SMTP</h2> 22 23<p> When an SMTP server announces support for the XFORWARD command, 24an SMTP client may send information that overrides one or more 25client-related logging attributes. The XFORWARD command targets 26the following problem: </p> 27 28<ul> 29 30 <li> <p> Logging after SMTP-based content filter. With the 31 deployment of Internet->MTA1->filter->MTA2 style 32 content filter applications, the logging of client and message 33 identifying information changes when MTA1 gives the mail to 34 the content filter. To simplify the interpretation of MTA2 35 logging, it would help if MTA1 could forward remote client 36 and/or message identifying information through the content 37 filter to MTA2, so that the information could be logged as part 38 of mail handling transactions. </p> 39 40</ul> 41 42<p> This extension is implemented as a separate ESMTP command, and 43can be used to transmit client or message attributes incrementally. 44It is not implemented by passing additional parameters via the MAIL 45FROM command, because doing so would require extending the MAIL 46FROM command length limit by another 600 or more characters beyond 47the space that is already needed to support other extensions such 48as AUTH and DSN. </p> 49 50<h2>XFORWARD Command syntax</h2> 51 52<p> An example of a client-server conversation is given at the end 53of this document. </p> 54 55<p> In SMTP server EHLO replies, the keyword associated with this 56extension is XFORWARD. The keyword is followed by the names of the 57attributes that the XFORWARD implementation supports. </p> 58 59<p> After receiving the server's announcement for XFORWARD support, 60the client may send XFORWARD requests at any time except in 61the middle of a mail delivery transaction (i.e. between MAIL and 62RSET or DOT). The command may be pipelined when the server supports 63ESMTP command pipelining. </p> 64 65<p> The syntax of XFORWARD requests is described below. Upper case 66and quoted strings specify terminals, lowercase strings specify 67meta terminals, and SP is whitespace. Although command and attribute 68names are shown in upper case, they are in fact case insensitive. 69</p> 70 71<blockquote> 72<p> 73 xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value ) 74</p> 75<p> 76 attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | IDENT | SOURCE ) 77</p> 78<p> 79 attribute-value = xtext 80</p> 81</blockquote> 82 83<ul> 84 85 <li> <p> Attribute values are xtext encoded as per RFC 1891. 86 </p> 87 88 <li> <p> The NAME attribute specifies the up-stream hostname, 89 or [UNAVAILABLE] when the information is unavailable. The 90 hostname may be a non-DNS hostname. </p> 91 92 <li> <p> The ADDR attribute specifies the up-stream network 93 address: a numerical IPv4 network address, an IPv6 address 94 prefixed with IPV6:, or [UNAVAILABLE] when the address information 95 is unavailable. Address information is not enclosed with []. 96 </p> 97 98 <li> <p> The PORT attribute specifies an up-stream client TCP 99 port number in decimal, or [UNAVAILABLE] when the information 100 is unavailable. </p> 101 102 <li> <p> The PROTO attribute specifies the mail protocol for 103 receiving mail from the up-stream host. This may be an SMTP or 104 non-SMTP protocol name of up to 64 characters, or [UNAVAILABLE] 105 when the information is unavailable. </p> 106 107 <li> <p> The HELO attribute specifies the hostname that the 108 up-stream host announced itself with (not necessarily via the 109 SMTP HELO command), or [UNAVAILABLE] when the information is 110 unavailable. The hostname may be a non-DNS hostname. </p> 111 112 <li> <p> The IDENT attribute specifies a local message identifier 113 on the up-stream host, or [UNAVAILABLE] when the information 114 is unavailable. The down-stream MTA may log this information 115 together with its own local message identifier to facilitate 116 message tracking across MTAs. </p> 117 118 <li> <p> The SOURCE attribute specifies LOCAL when the message 119 was received from a source that is local with respect to the 120 up-stream host (for example, the message originated from the 121 up-stream host itself), REMOTE for all other mail, or [UNAVAILABLE] 122 when the information is unavailable. The down-stream MTA may 123 decide to enable features such as header munging or address 124 qualification with mail from local sources but not other sources. 125 </p> 126 127</ul> 128 129<p> Note 1: an attribute-value element must not be longer than 130255 characters (specific attributes may impose shorter lengths). 131After xtext decoding, attribute values must not contain control 132characters, non-ASCII characters, whitespace, or other characters 133that are special in message headers. </p> 134 135<p> Note 2: DNS hostnames can be up to 255 characters long. The 136XFORWARD client implementation must not send XFORWARD commands that 137exceed the 512 character limit for SMTP commands. </p> 138 139<p> Note 3: [UNAVAILABLE] may be specified in upper case, lower 140case or mixed case. </p> 141 142<p> Note 4: Postfix implementations prior to version 2.3 do not 143xtext encode attribute values. Servers that wish to interoperate 144with these older implementations should be prepared to receive 145unencoded information. </p> 146 147<h2> XFORWARD Server operation </h2> 148 149<p> The server maintains a set of XFORWARD attributes with forwarded 150information, in addition the current SMTP session attributes. 151Normally, all XFORWARD attributes are in the undefined state, and 152the server uses the current SMTP session attributes for logging 153purposes. </p> 154 155<p> Upon receipt of an initial XFORWARD command, the SMTP server 156initializes all XFORWARD attributes to [UNAVAILABLE]. With each 157valid XFORWARD command, the server updates XFORWARD attributes with 158the specified values. </p> 159 160<p> The server must not mix client attributes from XFORWARD with 161client attributes from the current SMTP session. </p> 162 163<p> At the end of each MAIL FROM transaction (i.e. RSET or DOT), 164the server resets all XFORWARD attributes to the undefined state, 165and is ready to receive another initial XFORWARD command. </p> 166 167<h2> XFORWARD Server reply codes </h2> 168 169<blockquote> 170 171<table bgcolor="#f0f0ff" border="1"> 172 173<tr> <th> Code </th> <th> Meaning </th> </tr> 174 175<tr> <td> 250 </td> <td> success </td> </tr> 176 177<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr> 178 179<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr> 180 181<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr> 182 183<tr> <td> 550 </td> <td> insufficient authorization </td> </tr> 184 185</table> 186 187</blockquote> 188 189<h2>XFORWARD Example</h2> 190 191<p> In the following example, information sent by the client is 192shown in bold font. </p> 193 194<blockquote> 195<pre> 196220 server.example.com ESMTP Postfix 197<b>EHLO client.example.com</b> 198250-server.example.com 199250-PIPELINING 200250-SIZE 10240000 201250-VRFY 202250-ETRN 203250-XFORWARD NAME ADDR PROTO HELO 204250 8BITMIME 205<b>XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b> 206250 Ok 207<b>XFORWARD HELO=spike.porcupine.org</b> 208250 Ok 209<b>MAIL FROM:<wietse@porcupine.org></b> 210250 Ok 211<b>RCPT TO:<user@example.com></b> 212250 Ok 213<b>DATA</b> 214354 End data with <CR><LF>.<CR><LF> 215<b>. . .<i>message content</i>. . .</b> 216<b>.</b> 217250 Ok: queued as 3CF6B2AAE8 218<b>QUIT</b> 219221 Bye 220</pre> 221</blockquote> 222 223<h2>Security</h2> 224 225<p> The XFORWARD command changes audit trails. Use of this command 226must be restricted to authorized clients. </p> 227 228<h2>SMTP connection caching</h2> 229 230<p> SMTP connection caching makes it possible to deliver multiple 231messages within the same SMTP session. The XFORWARD attributes are 232reset after the MAIL FROM transaction completes (after RSET or DOT), 233so there is no risk of information leakage. </p> 234 235<h2> References </h2> 236 237<p> Moore, K, "SMTP Service Extension for Delivery Status Notifications", 238RFC 1891, January 1996. </p> 239 240</body> 241 242</html> 243
