Demo
Demo

Knowledge base

PMTA knowledge base›Block <proxy>›Directive§ 3.3.22.4

include-tlv

<proxy>

Whether to pass the queue domain to the proxy
in the configuration this is a lineinclude-tlv the VirtualMTA's proxy-include-tlv, then the global settinginside the block <proxy>
What the proxy learns about the message

The line adds an extra field with the queue domain to the protocol header. There is only one type so far — domain, and the engine fills in the value itself.

It requires the second protocol version — the first simply has no extra fields. The default chain is the same as for the version: not set here — proxy-include-tlv on the sending address is looked at, then on the node.

The queue domain is not always the recipient domain. It is the queue name, and it changes with MX rollup or when a queue is renamed. That is, the proxy will get what the node considers the direction, not what is written in the recipient’s address.

Why the proxy needs it. The only point is to give it grounds for a decision: spreading traffic across outgoing addresses, applying its own limits, keeping its own statistics by direction. Without this field the proxy sees only a pair of addresses.

The main trap is expecting the recipient’s address in the field. It holds the queue name. With MX rollup on, a dozen domains will merge into one name, and a proxy that spreads traffic by domain will see something other than it expected.
What the Hub does. It does not write it: there are no <proxy> blocks in the configuration. The gate gets the queue domain from the proxy-include-tlv domain line in every sending address that goes through a proxy.
Recommended values

There is only one value so far; the question is whether to enable it:

Value When
do not set it the proxy decides by the pair of addresses
domain the proxy spreads traffic by direction

A mandatory condition is the second protocol version.

The only field type, its code, the automatic substitution of the queue domain and the second-version requirement come from the manual (§ 3.3.22.4). The remark about MX rollup comes from there too.
Example configuration
# the field works only together with the second version
<proxy mta-proxy>
    server proxy.internal:9999
    client 16.80.77.101 client2.hostname.com
    protocol-version 2
    include-tlv domain</proxy>
The field will carry the queue name. With MX rollup this is not the recipient’s domain name but the group’s common name.
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▶

Enabling the field with the first protocol version

§ 3.3.22.4

What it costsThe first version has no extra fields. The line will silently add nothing, and the proxy will keep seeing only a pair of addresses.
How to spot itThe line is set, but the proxy does not receive the domain.
How to do it rightSet protocol-version 2 — here or at a level above.
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
include-tlv <enumeration>
Values
domain
Default
the VirtualMTA's proxy-include-tlv, then the global setting § 3.3.22.4
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<proxy>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line lives in <proxy> and overrides the two levels above: proxy-include-tlv on the sending address, then the same line at the node level.
⇄

Related directives

3 relations

Does not work without

protocol-version<proxy>Requires the second protocol version: the first has no extra fields. § 3.3.22.4

Same name in other blocks

proxy-include-tlvGlobalA level lower in precision: this line overrides it. § 3.3.22.4

Applies to

A named proxy and three levels of its settingsThe mechanism for which this line adds a field to the header. § 3.3.22.4

How to check on the node
Check it on the proxy — in the connection header:
tcpdump -A -i any -c 20 'port 5000'
In the second protocol version the field comes as a binary block with code 0xE0 and the domain string in UTF-8. It is easier to parse on the proxy itself, in its log.
◇

What else to read

3 articles

◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.◇The sending address — what it is made ofA named set of everything that is a property of the address: which IP the message leaves from, how the node introduces itself, what it signs with and how fast it sends.◇A named proxy and three levels of its settingsThe block carries the proxy address, the external sending address, the protocol version, the field type and the number of attempts; the first two lines are required.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Sending through proxies
Neighboring settings of the block <proxy>:clientserverprotocol-versionretry-attemptsAll 5 directives of the block →