1
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2
"http://www.w3.org/TR/html4/loose.dtd">
8
<title>Postfix XCLIENT Howto</title>
10
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
16
<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix XCLIENT Howto</h1>
20
<h2>Purpose of the XCLIENT extension to SMTP</h2>
22
<p> The XCLIENT command targets the following problems: </p>
26
<li> <p> Access control tests. SMTP server access rules are
27
difficult to verify when decisions can be triggered only by
28
remote clients. In order to facilitate access rule testing,
29
an authorized SMTP client test program needs the ability to
30
override the SMTP server's idea of the SMTP client hostname,
31
network address, and other client information, for the entire
32
duration of an SMTP session. </p>
34
<li> <p> Client software that downloads mail from an up-stream
35
mail server and injects it into a local MTA via SMTP. In order
36
to take advantage of the local MTA's SMTP server access rules,
37
the client software needs the ability to override the SMTP
38
server's idea of the remote client name, client address and
39
other information. Such information can typically be extracted
40
from the up-stream mail server's Received: message header. </p>
42
<li> <p> Post-filter access control and logging. With
43
Internet->filter->MTA style content filter applications,
44
the filter can be simplified if it can delegate decisions
45
concerning mail relay and other access control to the MTA. This
46
is especially useful when the filter acts as a transparent
47
proxy for SMTP commands. This requires that the filter can
48
override the MTA's idea of the SMTP client hostname, network
49
address, and other information. </p>
53
<h2>XCLIENT Command syntax</h2>
55
<p> Examples of client-server conversations are given at the end
56
of this document. </p>
58
<p> In SMTP server EHLO replies, the keyword associated with this
59
extension is XCLIENT. It is followed by the names of the attributes
60
that the XCLIENT implementation supports. </p>
62
<p> The XCLIENT command may be sent at any time except in the middle
63
of a mail delivery transaction (i.e. between MAIL and DOT). The
64
XCLIENT command may be pipelined when the server supports ESMTP
65
command pipelining. </p>
67
<p> The syntax of XCLIENT requests is described below. Upper case
68
and quoted strings specify terminals, lowercase strings specify
69
meta terminals, and SP is whitespace. Although command and attribute
70
names are shown in upper case, they are in fact case insensitive.
75
xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value )
78
attribute-name = ( NAME | ADDR | PROTO | HELO )
84
<li> <p> The NAME attribute specifies an SMTP client hostname
85
(not an SMTP client address), [UNAVAILABLE] when client hostname
86
lookup failed due to a permanent error, or [TEMPUNAVAIL] when
87
the lookup error condition was transient. </p>
89
<li> <p> The ADDR attribute specifies an SMTP client numerical
90
IPv4 network address, an IPv6 address prefixed with IPV6:, or
91
[UNAVAILABLE] when the address information is unavailable.
92
Address information is not enclosed with []. </p>
94
<li> <p> The PROTO attribute specifies either SMTP or ESMTP.
97
<li> <p> The HELO attribute specifies an SMTP HELO parameter
98
value, or the value [UNAVAILABLE] when the information is
103
<p> Note 1: syntactically valid NAME and HELO attributes can be up
104
to 255 characters long. The client must not send XCLIENT commands
105
that exceed the 512 character limit for SMTP commands. To avoid
106
exceeding the limit the client should send the information in
107
multiple XCLIENT commands. </p>
109
<p> Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified
110
in upper case, lower case or mixed case. </p>
112
<p> The XCLIENT server reply codes are as follows: </p>
116
<table border="1" bgcolor="#f0f0ff">
118
<tr> <th> Code </th> <th> Meaning </th> </tr>
120
<tr> <td> 250 </td> <td> success </td> </tr>
122
<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr>
124
<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr>
126
<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr>
132
<h2>XCLIENT Examples</h2>
134
<p> In the first example, the client impersonates a mail originating
135
system by passing all SMTP session information via XCLIENT commands.
136
Information sent by the client is shown in bold font.
141
220 server.example.com ESMTP Postfix
142
<b>EHLO client.example.com</b>
143
250-server.example.com
148
250-XCLIENT NAME ADDR PROTO HELO
150
<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP </b>
152
<b>XCLIENT HELO=spike.porcupine.org</b>
154
<b>MAIL FROM:<wietse@porcupine.org></b>
156
<b>RCPT TO:<user@example.com></b>
159
354 End data with <CR><LF>.<CR><LF>
160
<b>. . .<i>message content</i>. . .</b>
162
250 Ok: queued as 763402AAE6
168
<p> In the second example, the client impersonates a mail originating
169
system by sending the XCLIENT command before the EHLO or HELO command.
170
This increases the realism of impersonation, but requires that the
171
client knows ahead of time what XCLIENT options the server supports.
176
220 server.example.com ESMTP Postfix
177
<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2</b>
179
<b>HELO spike.porcupine.org</b>
180
250 server.example.com
181
<b>MAIL FROM:<wietse@porcupine.org></b>
183
<b>RCPT TO:<user@example.com></b>
186
354 End data with <CR><LF>.<CR><LF>
187
<b>. . .<i>message content</i>. . .</b>
189
250 Ok: queued as CF1E52AAE7
197
<p> The XCLIENT command changes audit trails and/or SMTP client
198
access permissions. Use of this command must be restricted to
199
authorized SMTP clients. However, the XCLIENT command should not
200
override its own access control mechanism. </p>
202
<h2>SMTP connection caching</h2>
204
<p> XCLIENT attributes persist until the end of an SMTP session.
205
If one session is used to deliver mail on behalf of different SMTP
206
clients, the XCLIENT attributes need to be reset as appropriate
207
before each MAIL FROM command. </p>
added
removed
html/XCLIENT_README.html
