Forwarding parameters in IMAP/POP3/LMTP/SMTP proxying

Dovecot supports proxying various pieces of information and even variables for various protocols when forwarding connection. It requires that the sender is listed under login_trusted_networks. For IMAP, it uses the ID command, for other protocols, XCLIENT is used.

This feature is supported since v1.2, except for parameter forwarding, which was added in v2.2.29.

IMAP protocol

For IMAP protocol, this is done by extending the ID (RFC 2971) command.

• RFC Requirements

  • Maximum key length is 30 bytes.

  • Value strings MUST NOT be longer than 1024 octets.

    • Dovecot has exactly 1024 byte limit to values. Trying to send 1025 bytes results in “BYE Input buffer full, aborting” response.

  • Implementations MUST NOT send more than 30 field-value pairs.

    • That being said, there doesn’t seem to be any limit to number of field-value pairs Dovecot can accept. In a test of thousands of pairs sent to Dovecot, there was not any increased memory usage (since each key-value pair was read separately and then discarded when not used).

The parameters are forwarded as part of the ID command field-value list.

5 ID ("x-originating-ip" "127.0.0.1" "x-originating-port" "143" ...)

Supported Fields

Field	Description
x-originating-ip	Client IP address
x-originating-port	Client port
x-connected-ip	Server IP address
x-connected-port	Server port address
x-proxy-ttl	TTL which is reduced by each hop, loop prevention. When TTL drops to 0, the connection is dropped.
x-session-id / x-session-ext-id	Session ID to be used.
x-forward-<variable_name>	Forwarded variable, see Variables

POP3 protocol

For POP3 protocol, this is done with custom XCLIENT command which accepts a space separated list of field=value parameters.

Warning

There is a 1024 byte line limit for the XCLIENT command when using POP3. Reaching this limit would cause the XCLIENT command to fail. This would be visible to the POP3 client as “-ERR Input buffer full, aborting” or some other AUTH error.

Supported Fields

Field	Description
ADDR	Client IP
PORT	Client port
SESSION	Session ID
TTL	TTL which is reduced by each hop, loop prevention. When TTL drops to 0, the connection is dropped.
FORWARD	Base64-encoded, tab-separated list of key=value pairs to be forwarded to auth process. The keys and values are escaped using Dovecot’s tab-escape format.

SMTP/LMTP protocol

See https://www.postfix.org/XCLIENT_README.html

Supported Fields (SMTP & LMTP)

Field	Description
ADDR	Client IP; prefix (IPV6:<ipv6_address>) is required for IPv6. However, Dovecot currently forwards without the IPv6 prefix, which does not follow the correct Postfix XCLIENT syntax.
PORT	Client port
TTL	TTL which is reduced by each hop, loop prevention. When TTL drops to 0, the connection is dropped.
HELO	Original HELO/EHLO
LOGIN	Original LOGIN value
TIMEOUT	Original TIMEOUT
PROTO	Forwarded protocol: SMTP, ESTMP, or LMTP.

Supported Fields (SMTP/Submission ONLY)

Field	Description
FORWARD	Base64-encoded, tab-separated list of key=value pairs to be forwarded to auth process. The keys and values are escaped using Dovecot’s tab-escape format. This value is effectively limited to around 1000 bytes.
SESSION	Session ID

LMTP

Additional parameters supported for the LMTP RCPT TO command:

Parameter	Description
XRCPTFORWARD	Base64-encoded, tab-separated list of key=value pairs to be forwarded. The keys and values are escaped using Dovecot’s tab-escape format. This value is effectively limited to around 900 bytes.