HostingPingSearch
Hosting · WordPress · performance · infrastructure
explainer

Nginx proxy_bind transparent: Syntax, Linux CAP_NET_RAW Inheritance, and Kernel Routing Requirements

Short answer

Learn how Nginx proxy_bind transparent allows outgoing upstream connections to originate from non-local IP addresses, its Linux CAP_NET_RAW inheritance, and kernel routing table requirements.

By HostingPing editorial desk · Published

Research-based

Last verified:

Applies to: NGINX ngx_http_proxy_module and ngx_stream_proxy_module; documented versions 0.8.22+ HTTP and 1.9.2+ stream, with transparent support from 1.11.0 and Linux capability inheritance from 1.13.8

Comparison of NGINX HTTP and stream proxy_bind transparent support

In Nginx, the proxy_bind directive configures the local network address from which outgoing connections to a proxied server originate. When the transparent parameter is enabled—such as in proxy_bind $remote_addr transparent;—outgoing connections to the proxied server can originate from a non-local IP address, such as the client’s real IP address.

Documented Syntax and Module Availability

According to the official reference manuals for the ngx_http_proxy_module and the ngx_stream_proxy_module, the directive specification includes:

  • Syntax: proxy_bind address [ transparent ] | off;
  • Default: None (unspecified by default).
  • HTTP Context: http, server, location (introduced in version 0.8.22; port support added in 1.11.2).
  • Stream Context: stream, server (introduced in version 1.9.2).
  • Variables: Parameter values supporting variables appeared in version 1.3.12 for HTTP and version 1.11.2 for Stream.
  • The transparent Parameter: Added in version 1.11.0 for both HTTP and Stream modules.
  • Resetting via off: The special value off cancels the effect of a proxy_bind directive inherited from a previous configuration level, allowing the operating system to auto-assign the local IP address (and port in HTTP).

Superuser Requirements and Linux CAP_NET_RAW Inheritance

The documentation states that for the transparent parameter to work, it is usually necessary to run Nginx worker processes with superuser privileges. However, on Linux this is not required starting in version 1.13.8: when the transparent parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

Kernel Routing Table Requirement

The documentation explicitly notes an operating requirement when using transparent proxy binding: it is necessary to configure the kernel routing table to intercept network traffic from the proxied server. The primary documentation specifies this requirement as necessary for transparent operation, but does not provide specific routing commands or firewall rules.

How NGINX transparent binding depends on Linux capability and kernel routing

Text version of the diagrams

  • HTTP vs Stream Binding: HTTP module — http/server/location; Stream module — stream/server; Shared behavior — Non-local source address
  • Binding Needs System Support: NGINX config — proxy_bind transparent; Linux capability — Workers inherit CAP_NET_RAW; Kernel routing — Intercept upstream traffic

Research Method and Limitations

This explainer was prepared solely from the supplied public documentation excerpts for ngx_http_proxy_module and ngx_stream_proxy_module. Material limitations include reliance on bounded, partially truncated excerpts and the absence of accessible competing coverage. The official source states the requirement to configure the kernel routing table to intercept return traffic, but does not document specific Linux routing commands (such as ip rule, iptables, or nftables); therefore, no specific routing recipes or implementation commands are provided.

Related guides