242 lines
8.1 KiB
HTML
242 lines
8.1 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://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 <a href="https://tools.ietf.org/html/rfc1891">RFC 1891</a>.
|
|
</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",
|
|
<a href="https://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
|
|
|
|
</body>
|
|
|
|
</html>
|