yum upgrades for production use, this is the repository for you.
Active subscription is required.
NGINX proxy_pass: URI Rewriting, Variables, and DNS Gotchas — Technical Briefing
Problem Statement
The proxy_pass directive in NGINX has several non-obvious behaviors around URI rewriting, DNS resolution, and configuration placement. Misunderstanding these behaviors leads to common production failures: double slashes in paths, concatenated URIs, HTTP 502 errors after backend IP rotation, and configuration load failures. The root causes are threefold: NGINX rewrites URIs only under specific syntactic conditions, static hostnames are resolved once at startup (causing stale backend IPs to persist until reload), and certain configuration contexts forbid URI parts in proxy_pass.
Implementation Details
Three Forms of proxy_pass
proxy_pass accepts one of three value forms:
1. An upstream block name
2. A hostname/IP with optional port
3. A UNIX domain socket
Caveat: If an upstream block and a real DNS name share the same name, the upstream block wins at configuration load time.
URI Rewriting Rule
proxy_pass rewrites the request URI only when its value carries a URI part — anything after the host/port, even a lone /.
- Without a URI part: The original request URI passes unchanged to the backend.
- With a URI part: The location prefix is stripped from the request URI and replaced by the configured URI.
Trailing slash traps: Mismatched slashes between the location and proxy_pass URI parts cause double slashes (//x) or concatenation (/apix). Rule of thumb: keep both the location and proxy_pass URI parts consistent, ending both with a slash.
Variables Change Behavior
When a variable appears in proxy_pass, two behaviors change:
- URI rewriting must be done manually — e.g., by appending
$request_uri. - DNS resolution moves to request time. Without a
resolverdirective in scope, requests fail with HTTP 502 and the error log entry:no resolver defined to resolve .... Theresolverdirective accepts avalid=parameter that overrides DNS TTLs.
Variable-based workaround costs: Using variables for dynamic DNS bypasses upstream block features — no keepalive pooling, no load balancing, and no per-server failure accounting.
Placement Restrictions
proxy_pass is valid in location, if (inside location), and limit_except blocks.
Hard constraint: In regex locations, named locations, if statements, or limit_except blocks, proxy_pass must not carry a URI part (including a bare trailing slash), or NGINX refuses to start.
Rewrite interaction: If a rewrite directive changes the URI inside a location with a URI-carrying proxy_pass, the rewritten URI is used and the configured replacement URI is ignored.
Host Header Default
NGINX sends the backend a Host header equal to the proxy_pass hostname, not the client’s original Host header. Use proxy_set_header Host $host; to forward the original.
Frozen DNS Problem
Static hostnames in proxy_pass and upstream blocks resolve once at startup or reload. Backend IP rotation therefore causes 502/504 errors until a manual reload. Three escalating fixes exist:
Fix 1: Variable Workaround
Simple but loses upstream features (keepalive, load balancing, failure accounting) and adds latency on uncached lookups.
Fix 2: resolve Parameter (NGINX 1.27.3+)
Re-resolves in the background, honoring DNS TTLs. Requires:
– A shared memory zone in the upstream block
– A resolver directive in the upstream block
Version caveat: Verified on Rocky Linux 10 (NGINX 1.28.2). Enterprise Linux 9 and Ubuntu 24.04 top out at NGINX 1.24, which lacks this feature. Install the latest stable NGINX from the GetPageSpeed repository to obtain it.
Fix 3: nginx-module-upstream-jdomain
Provides a jdomain directive with:
– Request-driven re-resolution on a fixed interval
– No shared memory zone requirement
– Retention of last known good addresses during DNS outages
Installation (RPM-based):
sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-upstream-jdomain
Installation (APT-based):
sudo apt install nginx-module-upstream-jdomain
Module loading is automatic on Debian/Ubuntu — no load_module needed. On RPM systems, add at the top of nginx.conf:
load_module modules/ngx_http_upstream_jdomain_module.so;
jdomain parameters:
– port= — default 80
– interval= — seconds, default 1
– max_ips= — caps resolved addresses, default 4
– ipver=4 or ipver=6
– strict — marks upstream down on resolution failure instead of reusing stale addresses
Operational caveats:
– Initial resolution at startup is synchronous through /etc/resolv.conf. If unresolved, NGINX refuses to start with host not found in upstream.
– Each worker keeps its own re-resolution timer, so brief inconsistency across workers after DNS changes is expected.
Keepalive Pooling
With an upstream block, enable all three of:
keepalive 16;
proxy_http_version 1.1;
proxy_set_header Connection "";
All three are required. This works with jdomain for re-resolving DNS plus pooled connections.
Common Error Troubleshooting
| Error | Fix |
|---|---|
no resolver defined to resolve ... |
Add a resolver directive in scope |
"proxy_pass" cannot have URI part in location given by regular expression ... |
Remove URI part (including bare trailing slash) in regex locations, named locations, if, and limit_except blocks |
Double slashes or concatenated URIs (//x, /apix) |
Fix trailing-slash mismatch between location and proxy_pass |
host not found in upstream at startup with jdomain |
Fix /etc/resolv.conf or the DNS record |
| Wrong Host header | Add proxy_set_header Host $host; |
Practical Payoff
Correctly applying these rules eliminates the most common proxy_pass failure modes: path mangling from slash mismatches, startup failures from URI parts in forbidden contexts, and prolonged outages from stale DNS resolution. The jdomain module provides a production-grade dynamic DNS solution that preserves upstream features (keepalive pooling, load balancing) while surviving DNS outages via stale-address fallback — without requiring NGINX 1.27.3+ or shared memory zones.
Operational Note
GetPageSpeed Amplify runs scheduled gixy scans across hosts, tying findings to live NGINX runtime metrics. It is drop-in compatible with the deprecated nginx-amplify-agent (EOL January 2026). The jdomain module source is at nicholaschiasson/ngx_upstream_jdomain; GetPageSpeed packages it plus 140+ other modules in its Premium Repository.
Read the full article: NGINX proxy_pass: URI Rewriting, Variables, and DNS Gotchas
