Resolve proxy client-IP chains with an explicit NGINX trust contract

Choose the address signal before using it

A fictional AI endpoint receives all connections through a load balancer. A network-rate signal keyed only to that balancer would group unrelated callers together. Reading the first value of a forwarded field instead would let an unexplained input choose the key. The useful question is which address the receiving proxy derives under a specific, reviewed topology.

This guide proposes a narrow HTTP NGINX profile and an inert worksheet. It does not configure a running service or implement a rate limiter. Client IP is only one possible network-source signal; authenticated principal, tenant budgets and object permissions require independent controls.

Declare the module and fixed review target

The proposed target is an NGINX 1.28.0 HTTP build with the realip module explicitly enabled and the ordinary HTTP proxy module available. This is a fixed documentation-review target, not an installed-runtime observation or release recommendation. The current official references are unversioned; an actual adoption must reconcile the exact maintained build and effective configuration before relying on this profile.

The realip reference says the module is not built by default and requires --with-http_realip_module. Select X-Forwarded-For explicitly; the documented header default is X-Real-IP. Recursive search defaults to off. For a matching trusted original peer, off selects the last header address; on selects the last non-trusted address. This worksheet selects on.

Its required features predate the proposed target: recursive search is documented since 1.3.0/1.2.1 and the original-address variable since 1.9.7. No newer-only directive is assumed. PROXY protocol, UNIX sockets, hostname trust and alternate headers are outside this profile.

Establish provenance at the first trusted ingress

Use symbolic roles rather than real addresses. IP-A represents an ordinary client; L-A is trusted ingress; L-B is an optional second trusted proxy; N-A is the receiver. IP-A and invented prefix IP-X are outside the intended proxy trust set.

PROPOSED_UNRUN — topology labels, not requests or configuration
One hop:  IP-A -> L-A -> N-A
Two hops: IP-A -> L-A -> L-B -> N-A
N-A trusted peers: L-A and L-B only
N-A mode: explicit X-Forwarded-For, recursive on
L-A/L-B: no realip address rewriting
Application principal: independently authenticated

For the proposed positive path, L-A replaces caller-supplied X-Forwarded-For with its observed client address. L-B accepts only L-A’s established path and appends its own observed peer. No forwarding hop rewrites that address through realip. These are deployment prerequisites, not facts established about any real ingress.

The proxy reference documents proxy_set_header for redefining or appending fields. Its $proxy_add_x_forwarded_for appends $remote_addr to an existing X-Forwarded-For value, or uses that address alone when absent. Appending is therefore different from discarding an untrusted incoming chain.

It also documents an inheritance trap: parent proxy_set_header directives are inherited only when none are defined at the current level. A nested Host rewrite can therefore stop inheritance of the parent’s forwarding-field policy. Review the complete effective request context, rather than assume one global directive covers every route. This article supplies no configuration snippet or inheritance claim for other directives.

Keep the original peer and derived address distinct

The core reference defines $remote_addr as the client address. At N-A, realip can change that address. The realip reference separately defines $realip_remote_addr as retaining the original client address. Thus an intended two-hop derivation records original peer L-B and derived IP-A, rather than calling both “the client.”

For future verification, retain a minimized topology revision, expected peer role, selected trust policy, recursion setting and derivation disposition. Do not store complete headers or prompts by default. A derived address without its provenance status must not become an authenticated account field.

Review eight inert chain cases

Chains below are symbolic ordered address lists, not actual header strings. Every row is PROPOSED_UNRUN and assumes valid address representations where selection is discussed. Expected selections follow the documented rule; they are not observed NGINX results.

Name unsupported input and trust limits

The positive profile covers ordinary single-field IPv4 address lists without ports. The realip reference documents optional port replacement and IPv6 support, but this worksheet exercises neither. It specifies no parser for malformed or repeated fields and does not claim NGINX rejects them. Before using such traffic for attribution, the integration needs a separately supported admission contract; unknown behavior is not a trusted signal.

RFC 7239 standardizes Forwarded, while distinguishing the older X-Forwarded fields. Its integrity discussion warns that clients or intermediaries can alter forwarded information; trusting proxies also requires considering the preceding chain and secured communication. It identifies network-information and privacy exposure. This is not evidence that the selected realip header consumes Forwarded syntax.

A compromised trusted proxy can supply false data. Shared egress and changing addresses also limit interpretation. Do not infer a human identity, geography, complete abuse protection or permission to bypass another gate from an IP signal.

Require deployment evidence before calling the path covered

Future review must establish ingress replacement, intermediary behavior, direct-path exclusions, secured links, actual module availability and effective configuration. Verify every route that consumes the signal. The proposed source review cannot establish those properties or prove a firewall rule works.

No actual headers, addresses, requests, configuration, module probes or network/runtime experiments were created or run. Boundary is a prelaunch model request router and does not ship this reverse-proxy contract. Its synthetic action exercise and mock policy evidence concern different, limited behavior.