Postfix XCLIENT Howto


Purpose of the XCLIENT extension to SMTP

When an SMTP server announces support for the XCLIENT command, an SMTP client may send information that overrides one or more client-related session attributes. The XCLIENT command targets the following problems:

  1. 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.

  2. 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.

  3. 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.

XCLIENT Command syntax

An example client-server conversation is given at the end of this document.

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.

The XCLIENT command may be sent at any time, except in the middle of a mail delivery transaction (i.e. between MAIL and DOT, or MAIL and RSET). The XCLIENT command may be pipelined when the server supports ESMTP command pipelining. To avoid triggering spamware detectors, the command should be sent at the end of a command group.

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.

xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value )

attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | LOGIN )

attribute-value = xtext

Note 1: syntactically valid NAME and HELO attribute-value elements 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; for example, send NAME and ADDR last, after HELO and PROTO. Once ADDR is sent, the client is usually no longer authorized to send XCLIENT commands.

Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified in upper case, lower case or mixed case.

Note 3: 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.

Note 4: Some Postfix implementations do not implement the PORT or LOGIN attributes.

XCLIENT Server response

Upon receipt of a correctly formatted XCLIENT command, the server resets state to the initial SMTP greeting protocol stage. Depending on the outcome of optional access decisions, the server responds with 220 or with a suitable rejection code.

For practical reasons it is not always possible to reset the complete server state to the initial SMTP greeting protocol stage:

NOTE: Postfix implementations prior to version 2.3 do not jump back to the initial SMTP greeting protocol stage. These older implementations will not correctly simulate connection-level access decisions under some conditions.

XCLIENT server reply codes

Code Meaning
220 success
421 unable to proceed, disconnecting
501 bad command parameter syntax
503 mail transaction in progress
550 insufficient authorization
other connection rejected by connection-level access decision

XCLIENT Example

In the example, the client impersonates a mail originating system by passing all SMTP client information via the XCLIENT command. Information sent by the client is shown in bold font.

220 server.example.com ESMTP Postfix
EHLO client.example.com
250-server.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-XCLIENT NAME ADDR PROTO HELO
250 8BITMIME
XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2
220 server.example.com ESMTP Postfix
EHLO spike.porcupine.org
250-server.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-XCLIENT NAME ADDR PROTO HELO
250 8BITMIME
MAIL FROM:<wietse@porcupine.org>
250 Ok
RCPT TO:<user@example.com>
250 Ok
DATA
354 End data with <CR><LF>.<CR><LF>
. . .message content. . .
.
250 Ok: queued as 763402AAE6
QUIT
221 Bye

Security

The XCLIENT command changes audit trails and/or SMTP client access permissions. Use of this command must be restricted to authorized SMTP clients.

SMTP connection caching

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.

References

Moore, K, "SMTP Service Extension for Delivery Status Notifications", RFC 1891, January 1996.