Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 3.3.17.16

The load balancer header at the entrance

use-inbound-proxy
How the node recognizes a client behind a load balancer

A load balancer or a TLS-terminating device connects to the node under its own name, and the client’s real address is lost. The mechanism restores it: the node expects the PROXY header first and takes the address and port from it. It detects the version by itself, both of them.

The trio of lines is the same for both kinds of entry point — the mail listener and the Transmissions API entry point: use-inbound-proxy enables it, inbound-proxy-timeout limits the wait (five seconds by default, then disconnect), log-inbound-proxy shows what arrived.

🔴 Without this mechanism everything that looks at the source address collapses. Matching of the <source> block — and with it the right to send through the node, limits and processing of control headers — is computed from the client’s address. Having lost it, the node sees the same load balancer address for all submitters and stops telling them apart.

🔴 And right there is the opposite danger: the address becomes the client’s claim. Behind a load balancer in a closed network this is safe. On an entry point reachable from anywhere it is not: whoever connects can declare any address and get whatever rights that address has.

The main trap is enabling header acceptance on an entry point reachable from outside. It turns the source list from a check into a formality: the right to send goes to whoever claims the right address. The mechanism is designed for a closed network between the load balancer and the node.
What the Hub does. It does not write it: there is no load balancer in front of the nodes, submitters connect directly.

🔎 If one appears, it must be enabled at the same time as the balancer — the line without a load balancer closes every connection — and the entry point must then be closed to everyone except the load balancer itself. Otherwise the right to submit goes to anyone who claims our address.

Recommended values

The mechanism has no values of its own — it is enabled by three lines, the same for both kinds of entry point:

What Line Default
enable acceptance use-inbound-proxy off
how long to wait inbound-proxy-timeout 5 seconds
show what was received log-inbound-proxy off
Expecting the header first, auto-detecting the version, extracting the address and port, disconnecting on timeout and the same trio at both entry points come from the manual (§ 3.3.17.16–18, § 3.3.21.13–15). The analysis of the danger on an open entry point is ours.
Example configuration
# the entry point is closed to everyone except the load balancer — otherwise any address can be claimed
<smtp-listener 10.0.0.0/24:2525>
    use-inbound-proxy yes    inbound-proxy-timeout 1s
</smtp-listener>
The address restriction in the block name is not decoration here but a security condition of the mechanism.
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 ends2 mistakes▶

Enabling header acceptance on an entry point open to the outside

our experience

What it costsThe client’s address becomes whatever it declared itself. Whoever connects will claim a permitted address and get its rights — up to the right to send through the node.
How to spot itThe entry point listens on 0/0, and header acceptance is enabled.
How to do it rightNarrow the entry point down to the load balancer’s address.

Enabling the line before the load balancer appears

§ 3.3.17.16

What it costsNobody sends the header, and the node closes every connection. Receiving stops completely.
How to spot itAll connections drop right after being established.
How to do it rightEnable it together with the load balancer, not in advance.
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.
Inheritance
The mechanism has no inheritance — the directives that enable it are inherited, and they live inside their entry point. There can be several entry points, and header acceptance is enabled for each separately.
⇄

Related entries

2 relations

Same name in other blocks

A named proxy and three levels of its settingsThe outgoing half of the same protocol: there the node sets the header, here it reads it. § 3.3.17.16

Affects

How the node selects a source and combines its settingsThe address extracted from the header is what gets matched against the source list. § 3.3.17.16

Referenced from

use-inbound-proxy<smtp-listener>The mechanism this line enables. § 3.3.17.16

How to check on the node
The check is direct — connect bypassing the load balancer:
nc -zv NODE 2525
The connection must close: no header will come from nc. If it stays open, header acceptance is not enabled. And if it goes through from any address, the entry point is open wider than it should be.
◇

What else to read

3 articles

◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇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.◇What the submission bindings needWhat must be in place on the submitting side for the bindings to work: a library, permissions and group membership.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Node security · Connect a sending platform