212 lines
6.4 KiB
HTML
212 lines
6.4 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"http://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
<html>
|
|
|
|
<head>
|
|
|
|
<title>Postfix XCLIENT 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 XCLIENT Howto</h1>
|
|
|
|
<hr>
|
|
|
|
<h2>Purpose of the XCLIENT extension to SMTP</h2>
|
|
|
|
<p> The XCLIENT command targets the following problems: </p>
|
|
|
|
<ol>
|
|
|
|
<li> <p> Access control tests. SMTP server access rules are
|
|
difficult to verify when decisions can be triggered only by
|
|
remote clients. In order to facilitate access rule testing,
|
|
an authorized SMTP client test program needs the ability to
|
|
override the SMTP server's idea of the SMTP client hostname,
|
|
network address, and other client information, for the entire
|
|
duration of an SMTP session. </p>
|
|
|
|
<li> <p> Client software that downloads mail from an up-stream
|
|
mail server and injects it into a local MTA via SMTP. In order
|
|
to take advantage of the local MTA's SMTP server access rules,
|
|
the client software needs the ability to override the SMTP
|
|
server's idea of the remote client name, client address and
|
|
other information. Such information can typically be extracted
|
|
from the up-stream mail server's Received: message header. </p>
|
|
|
|
<li> <p> Post-filter access control and logging. With
|
|
Internet->filter->MTA style content filter applications,
|
|
the filter can be simplified if it can delegate decisions
|
|
concerning mail relay and other access control to the MTA. This
|
|
is especially useful when the filter acts as a transparent
|
|
proxy for SMTP commands. This requires that the filter can
|
|
override the MTA's idea of the SMTP client hostname, network
|
|
address, and other information. </p>
|
|
|
|
</ol>
|
|
|
|
<h2>XCLIENT Command syntax</h2>
|
|
|
|
<p> Examples of client-server conversations are given at the end
|
|
of this document. </p>
|
|
|
|
<p> In SMTP server EHLO replies, the keyword associated with this
|
|
extension is XCLIENT. It is followed by the names of the attributes
|
|
that the XCLIENT implementation supports. </p>
|
|
|
|
<p> The XCLIENT command may be sent at any time except in the middle
|
|
of a mail delivery transaction (i.e. between MAIL and DOT). The
|
|
XCLIENT command may be pipelined when the server supports ESMTP
|
|
command pipelining. </p>
|
|
|
|
<p> The syntax of XCLIENT 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>
|
|
xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value )
|
|
</p>
|
|
<p>
|
|
attribute-name = ( NAME | ADDR | PROTO | HELO )
|
|
</p>
|
|
</blockquote>
|
|
|
|
<ul>
|
|
|
|
<li> <p> The NAME attribute specifies an SMTP client hostname
|
|
(not an SMTP client address), [UNAVAILABLE] when client hostname
|
|
lookup failed due to a permanent error, or [TEMPUNAVAIL] when
|
|
the lookup error condition was transient. </p>
|
|
|
|
<li> <p> The ADDR attribute specifies an SMTP client 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 PROTO attribute specifies either SMTP or ESMTP.
|
|
</p>
|
|
|
|
<li> <p> The HELO attribute specifies an SMTP HELO parameter
|
|
value, or the value [UNAVAILABLE] when the information is
|
|
unavailable. </p>
|
|
|
|
</ul>
|
|
|
|
<p> Note 1: syntactically valid NAME and HELO attributes can be up
|
|
to 255 characters long. The client must not send XCLIENT commands
|
|
that exceed the 512 character limit for SMTP commands. To avoid
|
|
exceeding the limit the client should send the information in
|
|
multiple XCLIENT commands. </p>
|
|
|
|
<p> Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified
|
|
in upper case, lower case or mixed case. </p>
|
|
|
|
<p> The XCLIENT server reply codes are as follows: </p>
|
|
|
|
<blockquote>
|
|
|
|
<table border="1" bgcolor="#f0f0ff">
|
|
|
|
<tr> <th> Code </th> <th> Meaning </th> </tr>
|
|
|
|
<tr> <td> 250 </td> <td> success </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> 421 </td> <td> unable to proceed, disconnecting </td> </tr>
|
|
|
|
</table>
|
|
|
|
</blockquote>
|
|
|
|
<h2>XCLIENT Examples</h2>
|
|
|
|
<p> In the first example, the client impersonates a mail originating
|
|
system by passing all SMTP session information via XCLIENT commands.
|
|
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-XCLIENT NAME ADDR PROTO HELO
|
|
250 8BITMIME
|
|
<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b>
|
|
250 Ok
|
|
<b>XCLIENT 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 763402AAE6
|
|
<b>QUIT</b>
|
|
221 Bye
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> In the second example, the client impersonates a mail originating
|
|
system by sending the XCLIENT command before the EHLO or HELO command.
|
|
This increases the realism of impersonation, but requires that the
|
|
client knows ahead of time what XCLIENT options the server supports.
|
|
</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
220 server.example.com ESMTP Postfix
|
|
<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2</b>
|
|
250 Ok
|
|
<b>HELO spike.porcupine.org</b>
|
|
250 server.example.com
|
|
<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 CF1E52AAE7
|
|
<b>QUIT</b>
|
|
221 Bye
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h2>Security</h2>
|
|
|
|
<p> The XCLIENT command changes audit trails and/or SMTP client
|
|
access permissions. Use of this command must be restricted to
|
|
authorized SMTP clients. However, the XCLIENT command should not
|
|
override its own access control mechanism. </p>
|
|
|
|
<h2>SMTP connection caching</h2>
|
|
|
|
<p> XCLIENT attributes persist until the end of an SMTP session.
|
|
If one session is used to deliver mail on behalf of different SMTP
|
|
clients, the XCLIENT attributes need to be reset as appropriate
|
|
before each MAIL FROM command. </p>
|
|
|
|
</body>
|
|
|
|
</html>
|