Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta>›Directive§ 3.3.12.8

proxy-protocol

<virtual-mta>set by the Hub

The PROXY protocol version for connections through a proxy — for one sending address
in the configuration this is a lineproxy-protocolinside the block <virtual-mta>
The same name 1:Global<virtual-mta>— some of them are other settings, some are the same one
The middle level of a three-level setting

The line sets the protocol header version — 1 or 2. The default is 1.

There are three levels, and this is the middle one. The most specific is protocol-version in the proxy block itself; if it is not set there, this line is used; if this one is not set either, the same line at the node level.

The second version is needed for additional fields — passing the queue domain (proxy-include-tlv) works only with it.

The proxy chooses the version, not the node: set the one it understands.

The main trap is forgetting about the third level. A line in the <proxy> block is stronger than this one, and the sending address setting does not affect it.
What the Hub does. It writes 2 in every sending address that goes through a proxy — in the proxy-<tag> blocks of /etc/pmta/proxy.txt. The second version was chosen to pass the queue domain to the gate.
Recommended values

The value is chosen by what the proxy can do:

Value When
1 (default) the proxy is old or the queue domain is not needed
2 passing the queue domain is needed
Both versions, the default of 1 and the order in which the levels override each other come from the manual (§ 3.3.1.48, § 3.3.22.3).
Example configuration
# the second version and passing the queue domain go as a pair
proxy-protocol 2proxy-include-tlv domain
These two do not override the line in the proxy block itself — there it is the most specific.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends1 mistake▶

Setting the second version for a proxy that knows the first

our experience

What it costsThe proxy will not parse the header and will close the connection. The node will see an ordinary failure and move on to the next proxy or into retry.
How to spot itThe first proxy in the list never works.
How to do it rightMatch the version against the proxy’s configuration.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
proxy-protocol <see-global>
Values
1 or 2
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<virtual-mta>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line lives in <virtual-mta> and overrides the same node-level line for this sending address. It is itself overridden by the line of the same name in the <proxy> block.
⇄

Related directives

2 relations

Same name in other blocks

proxy-protocolGlobalThe level above: if not set here, the version is taken from there. § 3.3.1.48

Applies to

The sending address — what it is made ofA setting of one sending address: a neighboring one may have a different value. § 3.3.12.8

How to check on the node
The version is not visible from the node side — look at the proxy:
tcpdump -A -i any -c 20 'port 5000'
The first version starts with the text PROXY TCP4 …, the second with a binary signature.
◇

What else to read

3 articles

◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Neighboring settings of the block <virtual-mta>:host-namedomain-keysmtp-source-hostproxy-include-tlvinclude-headers-fromAll 15 directives of the block →