Proxy glossary

Definitions written to be precise rather than short. Where a term is used loosely in the industry, the entry says so and gives the distinction that matters.

Proxy types and roles#

Forward proxy#

An intermediary configured by the client, which sends its requests to the proxy instead of to the origin. The client knows the proxy exists, the origin usually does not. Used for egress control, filtering, caching and authentication. The wire-level signature is a request target in absolute form: GET http://example.com/ HTTP/1.1. See forward proxy vs reverse proxy.

Reverse proxy#

An intermediary deployed by the origin operator, which clients reach as if it were the origin. Clients usually do not know it exists. Used for TLS termination, load balancing, routing, caching and as a security boundary. The wire signature is a normal origin-form request with a Host header.

Transparent proxy#

A proxy that traffic is routed through without any client configuration, typically by policy routing or a firewall redirect. Strictly, RFC 2616 used "transparent" to mean a proxy that does not modify messages, while RFC 3040 uses "intercepting" for the diverted-traffic sense. Both meanings are in circulation. See transparent and intercepting proxies.

Egress proxy#

A forward proxy that all outbound traffic from a network or a workload is required to pass through, usually with an allowlist. The strongest architectural control against SSRF, because it moves the destination decision out of the application.

Open proxy#

A proxy that accepts requests from unauthenticated or unexpected sources and will connect onward to arbitrary destinations. Almost always accidental, and always a liability. See open proxies and misconfigured relays.

Sidecar proxy#

A proxy running alongside a single application instance, handling both its inbound and outbound traffic. It is a reverse proxy on the inbound leg and a forward proxy on the outbound leg simultaneously, which is why the forward/reverse distinction stops being a property of the software and becomes a property of the direction.

L4 proxy#

A proxy operating on TCP or UDP connections without parsing the application protocol. It can route on address, port and, with a TLS inspector, the SNI, but it cannot read or add HTTP headers. This is why an L4 proxy needs the PROXY protocol to preserve the client address.

L7 proxy#

A proxy that parses the application protocol, typically HTTP. It can route on path, method and headers, rewrite the request, enforce limits, and add forwarding headers. It also becomes a second HTTP implementation in the path, which is where request smuggling comes from.

Client identity#

X-Forwarded-For#

A de facto, unspecified request header holding a comma-separated list of addresses, oldest first, each hop appending the peer it received the connection from. Because the leftmost entry originates from the client, it is attacker controlled. The correct read is a right-to-left walk over trusted hops. See the X-Forwarded-For header and the client IP resolver.

Forwarded#

The standardised replacement for the X-Forwarded-* family, defined in RFC 7239, carrying for, by, host and proto parameters in one structured header. Correct, well specified, and much less widely deployed. See the Forwarded header.

X-Real-IP#

A single-valued convention holding one address, typically overwritten rather than appended by each hop. Simpler to consume than X-Forwarded-For and correspondingly easier to get wrong, because a forged value and a legitimate one look identical.

PROXY protocol#

A small block prepended to a TCP connection before any application bytes, carrying the original source and destination. v1 is ASCII text, v2 is binary and can carry TLVs including ALPN, SNI and TLS client certificate details. Not an RFC. See the PROXY protocol and the decoder.

Trusted proxy#

A hop whose forwarding headers you are willing to believe, identified either by a CIDR list or by a fixed position in the chain. The trust boundary must be enforced by the network, not by convention. See configuring trusted proxies.

Trust hop count#

A trust model that counts a fixed number of hops from the right of X-Forwarded-For rather than matching addresses, used by Envoy's xff_num_trusted_hops among others. Robust when the addresses in front of you change but the number of hops does not, and silently wrong the moment someone adds a hop.

TLS#

TLS termination#

The proxy completes the TLS handshake, holds the certificate and private key, and sees plaintext. Required for any HTTP-level routing, header manipulation or caching.

TLS passthrough#

The proxy forwards the encrypted bytes without decrypting them. The origin holds the certificate. Routing is limited to what is visible in the handshake, which in practice means the SNI. See TLS termination, passthrough and re-encryption.

Re-encryption#

Also called TLS bridging. The proxy terminates the client's TLS session and opens a new one to the upstream. Whether this is meaningful security or theatre depends entirely on whether the proxy verifies the upstream certificate.

SNI#

Server Name Indication, a TLS extension carrying the hostname the client intends to reach, sent in the clear in the ClientHello. It is what makes name-based routing possible without decryption, and what Encrypted Client Hello is designed to hide. See SNI-based routing.

ALPN#

Application-Layer Protocol Negotiation, the TLS extension used to agree on HTTP/1.1, HTTP/2 or another protocol during the handshake. Because it is negotiated per TLS session, the protocol version is a property of a single hop, not of the whole chain.

mTLS#

Mutual TLS, where both ends present certificates. When a proxy terminates TLS, the client certificate stops at the proxy, so the proxy must verify it and forward the identity in a header, which then has to be stripped from inbound requests to prevent forgery. See mutual TLS through a proxy.

TLS interception#

An intercepting proxy generating leaf certificates on the fly, signed by a CA installed in the client's trust store, so it can read and modify TLS traffic. The source of most unable to get local issuer certificate errors on corporate networks. See TLS interception and corporate root CAs.

Protocol mechanics#

CONNECT#

The HTTP method that asks a proxy to open a raw TCP tunnel to a host and port, after which the proxy relays opaque bytes. How HTTPS works through a forward proxy. See HTTP CONNECT tunnelling.

Extended CONNECT#

The HTTP/2 mechanism defined in RFC 8441 that allows protocols such as WebSocket to run over an HTTP/2 stream, replacing the HTTP/1.1 Upgrade handshake which HTTP/2 does not have.

Hop-by-hop header#

A header that applies to a single connection and must not be forwarded, including Connection, Keep-Alive, Transfer-Encoding, Upgrade, TE, Trailer, Proxy-Authorization and Proxy-Authenticate. Proxies strip them, which is exactly why WebSocket upgrades need explicit configuration in nginx.

Origin form and absolute form#

Two shapes of the HTTP request target. Origin form is GET /path HTTP/1.1 with a Host header, sent to an origin or a reverse proxy. Absolute form is GET http://example.com/path HTTP/1.1, sent to a forward proxy. RFC 9112 gives absolute form precedence over Host, which is a smuggling primitive when two hops disagree.

SOCKS5#

A protocol, defined in RFC 1928, for relaying arbitrary TCP connections and UDP datagrams through a proxy, with its own handshake and authentication. Unlike an HTTP proxy it is protocol agnostic and cannot cache or inspect. The socks5 versus socks5h distinction in curl decides whether the hostname is resolved locally or by the proxy. See SOCKS5 vs HTTP proxy.

PAC file#

A JavaScript file defining FindProxyForURL(url, host), evaluated by the client for every request to decide which proxy to use. See PAC files and WPAD and the PAC file tester.

WPAD#

Web Proxy Auto-Discovery, the mechanism by which a client finds a PAC file without configuration, using DHCP option 252 and then DNS name devolution. Convenient and historically a rich source of vulnerabilities.

no_proxy#

An environment variable listing hosts that should be reached directly rather than through the configured proxy. It has no specification and every client implements it differently. See the no_proxy environment variable and the tester.

Configuration and behaviour#

proxy_pass#

The nginx directive that forwards a request to an upstream. Whether it contains a URI part decides whether the matched location prefix is replaced or the request URI is forwarded unchanged, which is the origin of the trailing slash confusion. See nginx proxy_pass and the trailing slash and the simulator.

Upstream#

The server or group of servers a proxy forwards to. Called a backend in HAProxy, a cluster in Envoy, a service in Traefik.

Buffering#

The proxy reading a full request body or response into memory or disk before forwarding it. Protects a slow upstream from a slow client, and breaks anything that streams. See proxy buffering and streaming responses.

Keep-alive#

Reusing a TCP connection for multiple requests. Client-side and upstream-side keep-alive are independent settings, and nginx does not use upstream keep-alive unless explicitly configured. See keep-alive and upstream connection pooling.

Idle timeout#

How long a connection may sit without traffic before it is closed. When the upstream's idle timeout is shorter than the proxy's, the proxy will occasionally write a request onto a connection the upstream is closing, producing an intermittent 502.

Timeout ladder#

The ordering of timeouts across a chain. Request timeouts should decrease inward so the hop closest to the work fails first. Idle timeouts run the opposite way. See timeout budgets and the ladder checker.

Health check#

A probe used to decide whether an upstream should receive traffic. Active checks are initiated by the proxy on a schedule, passive checks infer health from real request outcomes. Open source nginx has only passive checks. See health checks and upstream failover.

Connection draining#

Removing a backend from rotation while allowing in-flight requests to complete. Correct ordering is: fail the readiness check, wait longer than the proxy's check interval, then stop accepting.

Sticky session#

Routing every request in a session to the same backend, by cookie, source address hash or consistent hashing. See sticky sessions.

Consistent hashing#

A backend selection scheme, such as ring hash or maglev, where adding or removing a server remaps only a small fraction of keys, unlike modulo hashing which remaps nearly all of them.

Circuit breaker#

A limit on concurrent connections, requests or retries to an upstream, which sheds load rather than queueing it when the upstream is unhealthy. Envoy implements these explicitly per cluster.

Outlier detection#

Automatically ejecting a backend from the load balancing pool based on its observed error rate or latency, without a dedicated health check endpoint.

Caching#

Shared cache#

A cache serving more than one user, which is what a reverse proxy cache is. The distinction matters because Cache-Control: private forbids storage in a shared cache but permits it in a browser.

Cache key#

The identity under which a response is stored, by default derived from the method, host and URI. Including or excluding query parameters, and what Vary adds, decides your hit rate. See caching in reverse proxies.

Vary#

A response header naming the request headers that participate in the cache key. High-cardinality values such as User-Agent fragment a cache into near-uselessness.

stale-while-revalidate#

A Cache-Control extension allowing a cache to serve a stale response immediately while refreshing it in the background, trading strict freshness for latency and upstream load.

Cache stampede#

Many simultaneous requests for the same expired or missing key all reaching the upstream at once. Mitigated by request coalescing, which nginx calls proxy_cache_lock.

Failure modes#

502 Bad Gateway#

The proxy reached an upstream but the response was unusable or the connection broke. See 502 vs 503 vs 504.

503 Service Unavailable#

The proxy had no usable upstream to try, or refused the request itself through a rate limit or a maintenance rule.

504 Gateway Timeout#

The proxy gave up waiting for the upstream. A 504 with no corresponding upstream log line is the signature of an inverted timeout ladder.

421 Misdirected Request#

The server received a request for an authority it cannot serve, most often because a browser coalesced connections for two hostnames covered by the same certificate onto one HTTP/2 connection.

Request smuggling#

Two implementations in a chain disagreeing about where one request ends, so bytes the front end treats as body are treated by the back end as the start of a new request. Classes include CL.TE, TE.CL, TE.TE and HTTP/2 downgrade variants. See HTTP request smuggling.

SSRF#

Server-Side Request Forgery, where an application can be induced to make a request to an attacker-chosen destination, typically an internal service or a cloud metadata endpoint. A proxy can be the weapon or the control. See SSRF and the proxy layer.

Ephemeral port exhaustion#

Running out of source ports for outbound connections, caused by opening a new connection per request instead of reusing them. Presents as intermittent connection failures under load, long before any CPU or memory limit is reached.

Desync#

The state after a smuggling attack, where the connection between two hops has a partial request buffered, so the next legitimate request is prefixed by attacker-controlled bytes.

Networking terms proxies rely on#

NAT#

Network Address Translation, which rewrites addresses in packet headers while forwarding at layer 3. It does not terminate connections, so it is not a proxy, and the endpoint still negotiates directly with the client. See proxy vs VPN vs NAT vs load balancer.

TPROXY#

A Linux facility that lets a proxy accept connections destined for other addresses and originate connections using a spoofed source address, so an intercepting proxy can preserve the client IP end to end. Requires policy routing to bring return traffic back.

CGNAT#

Carrier-Grade NAT, where an ISP shares one public address across many subscribers, usually with the 100.64.0.0/10 range internally. It is why source IP hashing and IP-based rate limiting behave badly on mobile networks.

Anycast#

Announcing the same IP address from many locations so that routing sends each client to a nearby one. Standard for CDN and DNS edges, and the reason a CDN's address list is large and changes.