Postfix XFORWARD Howto


Purpose of the XFORWARD extension to SMTP

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:

This extension is implemented as a separate EMSTP 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.

XFORWARD Command syntax

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

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.

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.

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.

xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value )

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

attribute-value = xtext

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.

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.

Note 3: [UNAVAILABLE] may be specified in upper case, lower case or mixed case.

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.

XFORWARD Server operation

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.

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.

The server must not mix client attributes from XFORWARD with client attributes from the current SMTP session.

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.

XFORWARD Server reply codes

Code Meaning
250 success
421 unable to proceed, disconnecting
501 bad command parameter syntax
503 mail transaction in progress
550 insufficient authorization

XFORWARD Example

In the following example, 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-XFORWARD NAME ADDR PROTO HELO
250 8BITMIME
XFORWARD NAME=spike.porcupine.org ADDR=168.100.189.2 PROTO=ESMTP 
250 Ok
XFORWARD HELO=spike.porcupine.org
250 Ok
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 3CF6B2AAE8
QUIT
221 Bye

Security

The XFORWARD command changes audit trails. Use of this command must be restricted to authorized clients.

SMTP connection caching

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.

References

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