From b7c15c31519dc44c1f691e0466badd556ffe9423 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:18:56 +0200 Subject: Adding upstream version 3.7.10. Signed-off-by: Daniel Baumann --- html/XFORWARD_README.html | 241 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 html/XFORWARD_README.html (limited to 'html/XFORWARD_README.html') diff --git a/html/XFORWARD_README.html b/html/XFORWARD_README.html new file mode 100644 index 0000000..9a43e27 --- /dev/null +++ b/html/XFORWARD_README.html @@ -0,0 +1,241 @@ + + + + + + +Postfix XFORWARD Howto + + + + + + + +

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:

+ +

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

+ +

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.

+ +

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 | IDENT | SOURCE ) +
+
+ attribute-value = xtext +
+

+ +

Attribute values are xtext encoded as per RFC 1891. +
+ +
The NAME attribute specifies the up-stream hostname, + or [UNAVAILABLE] when the information is unavailable. The + hostname may be a non-DNS hostname.
+ +
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 []. +
+ +
The PORT attribute specifies an up-stream client TCP + port number in decimal, or [UNAVAILABLE] when the information + is unavailable.
+ +
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.
+ +
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.
+ +
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.
+ +
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. +
+ +

+ +

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
+ +

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.

+ + + + -- cgit v1.2.3