Baseline: NGINX Open Source through stable 1.26.x and mainline 1.27.1; covers batches 1.27.2, 1.28.0, 1.29.0, 1.30.0, and 1.31.0, plus relevant FreeNginx 1.27/1.29 and NGINX Plus through R36.
Reference index
| Reference | Topics |
|---|---|
| security-and-upgrades.md | CVEs, fixed-version boundaries, request hardening, unsafe legacy behavior |
| core-http-and-runtime.md | listeners, core HTTP behavior, variables, filters, rate controls, builds |
| upstreams-and-proxying.md | keepalive, runtime DNS, balancing, retries, HTTP/2 backends, trailers, caches |
| tls-certificates-and-quic.md | trust, OCSP, certificate loading and caches, ECH, TLS observability, QUIC |
| stream-mail-and-protocols.md | stream TLS, mail proxying, PROXY TLVs, GeoIP2, MQTT, cross-module handoff |
| nginx-plus-operations.md | support lifecycle, licensing, platforms, images, OIDC, ACME, API, key-value data |
Select the product line first
Treat NGINX Open Source, FreeNginx, and NGINX Plus as distinct product lines. Do not copy a FreeNginx-only directive into NGINX Open Source or assume a Plus-only directive exists in a standard build. This patch labels fork-specific and commercial features explicitly.
Upgrade and security gates
Prioritize fixed releases before configuration work:
| Exposure | Affected releases or condition | Minimum fixed boundary in this patch |
|---|---|---|
| HTTP/3 NULL dereference and use-after-free | 1.25.0–1.25.3 as applicable | 1.25.4 |
| Four HTTP/3 memory-safety flaws | 1.25.0–1.25.5 and 1.26.0 | 1.26.1 or 1.27.0 |
| MP4 buffer overread, CVE-2024-7347 | 1.5.13–1.27.0 | 1.26.2 or 1.27.1 |
| TLS 1.3 SNI session reuse bypassing client-certificate verification | before 1.27.4 | 1.27.4 |
| 1.28-series mail, TLS proxy, WebDAV, MP4, and QUIC issues | 1.28.0–1.28.2 as applicable | 1.28.3; some fixes land in 1.28.1/1.28.2 |
| 1.30-series request, rewrite, upstream, charset, QUIC, and OCSP flaws | 1.30.0–1.30.2 as applicable | 1.30.3; see the per-CVE table |
| Crafted HTTP/3 QUIC session use-after-free | before 1.31.2 | 1.31.2 |
Read security-and-upgrades.md for exact CVEs, affected configurations, and intermediate fixed releases. Do not treat a later feature release as evidence that its earlier patch releases are safe.
Breaking changes, defaults, and deprecations
Upstream keepalive and HTTP version defaults
Since 1.29.7, upstream connection caching defaults to keepalive 32 local; per worker, and HTTP proxying defaults to HTTP/1.1. local prevents reuse across locations that happen to reach the same address. Disable caching explicitly with keepalive 0 when required.
upstream backend {
server 127.0.0.1:8080;
keepalive 64 local;
}
Strict HTTP/2 and HTTP/3 connection headers
Current NGINX rejects HTTP/2 and HTTP/3 requests carrying Connection, Proxy-Connection, Keep-Alive, Transfer-Encoding, or Upgrade. It accepts TE only when its value is trailers. Remove hop-by-hop fields before protocol translation.
FreeNginx response and rate semantics
FreeNginx 1.29.1 rejects proxied HTTP/0.9 responses by default; opt in with proxy_allow_http09 only for a known legacy backend. It also ignores interim 1xx responses and offers proxy_allow_duplicate_chunked for duplicate chunked encoding.
FreeNginx 1.29.0 changes limit_rate to a leaky-bucket algorithm and makes limit_rate_after the burst allowance. Recheck existing rate-limit tuning; use send_min_rate and client_body_min_rate when a minimum transfer rate is required.
Safer XSLT behavior
FreeNginx no longer loads external character entities declared in an internal DTD subset by default. Enable xml_external_entities only for configurations that intentionally need them.
Configure and module migrations
- Use
--without-http_upstream_sticky_module;--without-http_upstream_stickyis deprecated. - Migrate NGINX Plus OpenTracing packages to the OpenTelemetry module; OpenTracing was removed in R34 after deprecation in R31.
- Replace
mqtt_rewrite_buffer_sizewithmqtt_buffersfor NGINX Plus MQTT buffer sizing.
NGINX Plus license enforcement
From R33, install a per-instance JWT license token and permit hourly usage reporting over a verified connection. An initial report is required after install or upgrade; without it, traffic processing stops unless the optional 180-day enforce_initial_report grace period is enabled. Use Instance Manager as a relay in restricted networks; R34 adds report-proxy support and R35 adds automatic renewal.
High-use configuration patterns
Resolve ordinary upstreams at runtime
From 1.27.3, standard builds support upstream resolver, resolver_timeout, and server parameters resolve and service. Put dynamically resolved groups in shared memory with zone.
upstream api {
zone api 64k;
resolver 10.0.0.53 valid=30s;
resolver_timeout 5s;
server api.example.com resolve;
}
For SRV discovery, add service=http; the lowest numeric priority is primary and later priorities are backups.
Proxy to HTTP/2 backends
Since 1.29.4, select HTTP/2 upstream proxying explicitly. Build with ngx_http_v2_module.
location / {
proxy_http_version 2;
proxy_pass https://backend;
}
Forward response trailers
Since 1.27.2, enable trailer forwarding and advertise trailer support to the backend.
proxy_set_header Connection "te";
proxy_set_header TE "trailers";
proxy_pass_trailers on;
Send Early Hints
From 1.29.0, NGINX accepts HTTP 103 responses from proxy and gRPC backends. Use early_hints to control whether preliminary hints reach the client before the final response.
Cache variable-selected certificates
Since 1.27.4, avoid reloading variable-selected certificate files for every handshake by configuring the relevant cache. Both caches 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;
Balance by response time
From 1.31.0, use least_time inside an upstream block when response-time-based selection is more appropriate than round robin or connection count.
Configure stream ALPN
From 1.31.0, use proxy_ssl_alpn to advertise ALPN protocols on TLS connections from the stream proxy to an upstream server.
Configure Encrypted ClientHello carefully
NGINX 1.29.4 adds ssl_ech_file for a PEM ECHConfig in HTTP and stream shared mode, currently requiring the OpenSSL ECH feature branch. Inspect $ssl_ech_status and $ssl_ech_outer_server_name when diagnosing negotiation. FreeNginx added TLS 1.3 ECH separately in 1.29.2; do not assume identical build requirements.
Reconstruct request authority safely
Use $host$is_request_port$request_port: $is_request_port expands to : only when $request_port is nonempty, avoiding a trailing colon for authorities without an explicit port.
Operational checks
- Revisit log alerts after QUIC handshake severity changes in 1.29.0 and the SSL alert reductions in 1.31.0.
- Check OpenSSL requirements before enabling certificate compression, ECH, signature-algorithm variables, or QUIC 0-RTT.
- Remember that an upstream
max_connswithoutzoneis per worker and cached idle connections can push totals above the configured number. - Treat SSL key logs as secrets. NGINX Plus
ssl_key_logandproxy_ssl_key_logemit SSLKEYLOGFILE data suitable for decryption tools. - Confirm OS support before a Plus R36 upgrade; its platform matrix adds and removes distributions and versions.