Nginx Knowledge Patch

NGINX Knowledge Patch

Use this skill when configuring, upgrading, building, or operating NGINX Open Source, FreeNGINX, or NGINX Plus. Select the product line before applying a directive: fork-specific and commercial features are labeled and are not portable to a standard open-source build.

Reference index

Upgrade and security gates

Check the exact product, branch, enabled modules, and patch release before changing configuration. A feature release number alone does not establish that all later security fixes are present.

• Upgrade HTTP/3 deployments across the applicable memory-safety floors before tuning QUIC. In particular, do not run an affected pre-1.31.2 build with HTTP/3 enabled.
• Treat initial 1.29 and 1.30 releases as missing later same-branch security fixes. Match the affected configuration to the per-CVE table in security-and-upgrades.md.
• Upgrade TLS client-authentication deployments affected by cross-server session reuse before relying on configuration changes as mitigation.
• Preserve the documented older-branch floors when maintaining a legacy installation; do not infer them from current release numbering.

Breaking changes and defaults

Upstream keepalive and proxy HTTP defaults

Since 1.29.7, upstream and proxied keepalive are enabled by default, HTTP proxying defaults to HTTP/1.1, and NGINX no longer sends a Connection proxy header by default. The local parameter scopes an explicitly configured upstream keepalive cache. Disable caching explicitly when required.

upstream backend {
    server 127.0.0.1:8080;
    keepalive 64 local;
}

Strict protocol parsing

Current HTTP/2 and HTTP/3 handling rejects Connection, Proxy-Connection, Keep-Alive, Transfer-Encoding, and Upgrade. TE is valid only as trailers. Newer request parsing also validates authority syntax strictly and rejects a lone LF in chunked bodies. Remove hop-by-hop fields in protocol translators and test nonconforming peers before upgrading.

FreeNGINX proxy and rate semantics

FreeNGINX 1.29.1 rejects proxied HTTP/0.9 responses by default, ignores interim 1xx responses, and provides compatibility switches for HTTP/0.9 and duplicate chunked encoding. FreeNGINX 1.29.0 changes limit_rate to a leaky-bucket algorithm and treats limit_rate_after as its burst allowance. Recheck existing throughput tuning.

Configure and module migrations

• Use --without-http_upstream_sticky_module; the shorter legacy option is deprecated.
• In NGINX Plus, replace mqtt_rewrite_buffer_size with mqtt_buffers.
• In NGINX Plus, migrate OpenTracing packages to OpenTelemetry; OpenTracing is unavailable from R34.
• In FreeNGINX, enable xml_external_entities only for trusted XSLT workloads that intentionally need external entities declared in an internal DTD.

NGINX Plus licensing

From R33, each instance needs a JWT license token and hourly usage reporting over a verified connection. The initial report after installation or upgrade is traffic-critical unless the optional 180-day enforce_initial_report grace period is enabled. Plan a direct path, report proxy, or Instance Manager relay before deployment.

High-use configuration patterns

Resolve ordinary upstreams at runtime

Standard builds support upstream resolver, resolver_timeout, and server parameters resolve and service. Put dynamically resolved groups in shared memory with zone. For SRV discovery, use a portless hostname; the lowest numeric priority is primary and later priorities are backups.

upstream api {
    zone api 64k;
    resolver 192.0.2.53 valid=30s;
    resolver_timeout 5s;
    server api.example.com service=http resolve;
}

Proxy to HTTP/2 backends

Select HTTP/2 upstream proxying explicitly and build with ngx_http_v2_module.

location / {
    proxy_http_version 2;
    proxy_pass https://backend;
}

Forward response trailers

Enable trailer forwarding and advertise support to an HTTP/1.1 backend.

location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;
}

Forward Early Hints

NGINX accepts HTTP 103 responses from proxy and gRPC backends. Use early_hints to control whether they reach the client before the final response.

location / {
    proxy_pass http://backend;
    early_hints on;
}

Cache variable-selected certificates

ssl_certificate_cache and proxy_ssl_certificate_cache avoid loading variable-selected certificate files for every handshake. Both are off until configured; inactive and valid default to 10 seconds and 60 seconds.

ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;

proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;

Preserve request authority

Use $host$is_request_port$request_port to retain an explicitly supplied port without appending a colon when the request had no port.

proxy_set_header Host $host$is_request_port$request_port;

Choose upstreams by response time

Use least_time in an upstream block when observed response latency is a better selection signal than round robin or active connection count.

upstream backend {
    least_time header;
    server 192.0.2.10:8080;
    server 192.0.2.11:8080;
}

Configure stream ALPN

Use proxy_ssl_alpn to advertise ALPN protocols on TLS connections from a stream proxy to its upstream. Use server-side ssl_alpn and $ssl_alpn_protocol when the client-facing stream listener selects a backend.

Configure ECH carefully

ssl_ech_file loads a PEM ECHConfig and currently requires the OpenSSL ECH feature branch. Diagnose negotiation with $ssl_ech_status and $ssl_ech_outer_server_name.

Operational checks

• Revisit log alerts after QUIC and SSL handshake severity changes; failures that moved from crit or error to info can otherwise disappear.
• Check TLS-library requirements before enabling certificate compression, ECH, signature-algorithm variables, or QUIC 0-RTT.
• Remember that max_conns without zone is per worker and that cached idle connections can make totals exceed the configured number.
• Protect ssl_key_log and proxy_ssl_key_log output as decryption secrets.
• Confirm the supported operating-system matrix before a Plus upgrade.