# Nginx Knowledge Patch > NGINX - Skill: `nevaberry/nginx-knowledge-patch` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add nevaberry/nginx-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/nginx-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/nginx-knowledge-patch --- # NGINX Knowledge Patch Use this skill when writing, reviewing, upgrading, or debugging NGINX Open Source, FreeNGINX, or NGINX Plus configuration. Identify the product line and exact patch release first; fork-only and commercial directives are not portable to a standard NGINX Open Source build. ## Reference index | Reference | Topics | | --- | --- | | [security-and-upgrades.md](references/security-and-upgrades.md) | CVEs, fixed-version boundaries, reporting, and legacy hazards | | [core-http-and-runtime.md](references/core-http-and-runtime.md) | HTTP parsing, listeners, variables, filters, rate controls, builds, and runtime behavior | | [upstreams-and-proxying.md](references/upstreams-and-proxying.md) | Discovery, balancing, keepalive, retries, proxy protocols, caches, and backend requests | | [tls-certificates-and-quic.md](references/tls-certificates-and-quic.md) | Trust, OCSP, certificate caches, ECH, key logs, TLS observability, and QUIC | | [stream-mail-and-protocols.md](references/stream-mail-and-protocols.md) | Stream and mail proxying, PROXY TLVs, GeoIP2, MQTT, and listener handoff | | [nginx-plus-operations.md](references/nginx-plus-operations.md) | Plus lifecycle, licensing, platforms, images, OIDC, ACME, API, and key-value data | ## Select the product line first - Treat NGINX Open Source, FreeNGINX, and NGINX Plus as distinct products. - Confirm module availability and build flags before adding a directive. - Do not infer Open Source support from a Plus feature or NGINX support from a FreeNGINX change. - For Plus, check the supported OS matrix, active support window, and license reporting path before upgrading. ## Security and upgrade gates Upgrade to a fixed patch release before attempting configuration mitigation. Do not assume the first release in a feature series contains later security fixes. | Exposure | Minimum fixed boundary | | --- | --- | | HTTP/3 CVE-2024-24989 and CVE-2024-24990 | `1.25.4` | | HTTP/3 CVE-2024-32760, CVE-2024-31079, CVE-2024-35200, and CVE-2024-34161 | `1.26.1` or `1.27.0` | | MP4 buffer overread, CVE-2024-7347 | `1.26.2` or `1.27.1` | | CVE-2025-23419 TLS session reuse issue | `1.26.3` or `1.27.4` | | 1.29-series mail authentication disclosure | `1.29.1` | | 1.29-series TLS-backend plaintext injection | `1.29.5` | | 1.29-series WebDAV, MP4, mail, PTR, and stream OCSP issues | `1.29.7` | | 1.30-series request, rewrite, upstream, charset, QUIC, and OCSP flaws | Use the precise `1.30.1`, `1.30.2`, or `1.30.3` gate in the security reference | | Crafted HTTP/3 QUIC-session use-after-free | `1.31.2` | Read [security-and-upgrades.md](references/security-and-upgrades.md) for exact affected configurations, CVEs, older-branch floors, and the unsanitized error-log caveat. ## Breaking changes and compatibility defaults ### Upstream keepalive and HTTP version defaults From 1.29.7, upstream connection caching and proxied keepalive are enabled by default, `proxy_http_version` defaults to HTTP/1.1, and NGINX no longer sends a `Connection` proxy header by default. Use `local` to keep an explicitly sized cache scoped to its upstream usage context. ```nginx upstream backend { server backend.example:8080; keepalive 64 local; } ``` Disable or retune caching explicitly when an application depends on connection churn or location isolation. ### Strict request parsing and hop-by-hop headers Current HTTP/2 and HTTP/3 handling rejects `Connection`, `Proxy-Connection`, `Keep-Alive`, `Transfer-Encoding`, and `Upgrade`. `TE` is valid only as `trailers`. Protocol translators must remove hop-by-hop fields. Host and port parsing follows RFC 3986, and a lone LF is rejected in chunked request or response bodies. Test legacy clients and upstreams during upgrades. ### FreeNGINX proxy compatibility FreeNGINX rejects proxied HTTP/0.9 responses by default, ignores interim 1xx responses, and provides narrowly scoped opt-ins for legacy HTTP/0.9 and duplicate chunked encoding. ```nginx location /legacy { proxy_pass http://legacy; proxy_allow_http09 on; proxy_allow_duplicate_chunked on; } ``` ### FreeNGINX transfer-rate semantics FreeNGINX uses a leaky-bucket `limit_rate`; `limit_rate_after` is the allowed burst. Recheck existing rate tuning, and use `send_min_rate` or `client_body_min_rate` when a minimum transfer rate is required. ### Safer XSLT behavior FreeNGINX does not load external character entities declared in an internal DTD subset by default. Enable `xml_external_entities` only for a trusted transformation that intentionally requires the legacy behavior. ### Configure and module migrations - Disable the upstream sticky module with `--without-http_upstream_sticky_module`; the shorter legacy option is deprecated. - On Plus, migrate OpenTracing to OpenTelemetry; OpenTracing is no longer packaged. - Replace Plus `mqtt_rewrite_buffer_size` with `mqtt_buffers`. ## High-use configuration patterns ### Resolve ordinary upstreams at runtime Put dynamically resolved upstream groups in shared memory. Configure an upstream resolver and mark servers with `resolve`; for SRV discovery, add `service` and omit the server port. ```nginx upstream api { zone api 64k; resolver 192.0.2.53 valid=30s; resolver_timeout 5s; server api.example.com service=http resolve; } ``` The lowest numeric SRV priority is primary; later priorities are backups. ### Proxy to an HTTP/2 backend Select HTTP/2 explicitly for the upstream. ```nginx location / { proxy_http_version 2; proxy_pass https://backend; } ``` ### Forward response trailers Enable trailer forwarding and advertise trailer support to an HTTP/1.1 backend. ```nginx location / { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection "te"; proxy_set_header TE "trailers"; proxy_pass_trailers on; } ``` ### Send Early Hints NGINX can accept HTTP 103 responses from proxy and gRPC backends. Use `early_hints` to decide whether they reach the client before the final response. ### Cache variable-selected certificates Both server-side and upstream-client certificate caches are off until configured. `max` sets LRU capacity; `inactive` and `valid` default to 10 and 60 seconds. ```nginx 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 an explicitly supplied request port Use the paired variables so an authority without an explicit port does not gain a trailing colon. ```nginx proxy_set_header Host $host$is_request_port$request_port; ``` ### Balance by observed response time Use `least_time` inside an upstream when response-time selection is preferable to round robin or connection count. ```nginx upstream backend { least_time header; server 192.0.2.10:8080; server 192.0.2.11:8080; } ``` ### Advertise ALPN to a stream TLS upstream ```nginx proxy_ssl on; proxy_ssl_alpn h2; ``` Do not confuse upstream `proxy_ssl_alpn` with server-side `ssl_alpn`. ## Operational checks - Revisit alert rules after QUIC and SSL handshake log-level changes. - Verify TLS-library and build requirements before enabling certificate compression, ECH, signature variables, or QUIC 0-RTT. - Remember that `max_conns` is per worker without `zone`; cached idle connections can also push totals above the configured number. - Protect `ssl_key_log` and `proxy_ssl_key_log` output as decryption secrets. - For Plus, an unavailable initial usage report can stop traffic unless the optional grace period is deliberately enabled.