Nginx Knowledge Patch (1.27.3 – 1.29.7)

Baseline: Nginx 1.26.x stable, basic awareness of 1.27.x mainline. Covers: 1.27.3 through 1.29.7 (2024-11-26 to 2026-03-24).

Index

Topic	Reference	Key features
Upstream & load balancing	references/upstream-and-load-balancing.md	Sticky sessions, DNS resolve, HTTP/2 proxying
TLS & security	references/tls-and-security.md	ECH, QUIC 0-RTT, ssl_key_log, certificate caching
HTTP & transport	references/http-and-transport.md	Early Hints, header inheritance, MPTCP, new variables

Breaking Changes

Upstream keepalive enabled by default (1.29.7)

keepalive 32 local is now the default for all upstream blocks. proxy_http_version defaults to 1.1 (was 1.0). The Connection header is no longer set to close by default.

The classic keepalive boilerplate is now unnecessary:

# Before 1.29.7 — required for keepalive to upstreams:
upstream backend {
    server 127.0.0.1:8080;
    keepalive 32;
}
location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

# Since 1.29.7 — keepalive works out of the box:
upstream backend {
    server 127.0.0.1:8080;
}
location / {
    proxy_pass http://backend;
}

The local parameter (default) means keepalive connections are NOT shared across different location blocks. Omit local to allow sharing: keepalive 32;.

To disable keepalive to upstreams: keepalive 0;.

TLSv1/TLSv1.1 disabled by default (1.27.3)

ssl_protocols now defaults to TLSv1.2 TLSv1.3. If you need legacy protocol support, set ssl_protocols explicitly.

New Directives Quick Reference

Directive / Parameter	Context	Since	Description
`sticky cookie\|route\|learn`	`upstream`	1.29.6	Session affinity (was nginx-plus only)
`server ... resolve`	`upstream`	1.27.3	DNS-based upstream resolution (was nginx-plus only)
`server ... route=`	`upstream`	1.29.6	Route identifier for sticky sessions
`server ... drain`	`upstream`	1.29.6	Graceful server removal
`proxy_http_version 2`	`location`	1.29.4	HTTP/2 proxying to backends
`early_hints`	`server`, `location`	1.29.0	Pass 103 Early Hints from backends
`add_header_inherit`	`http`, `server`, `location`	1.29.3	Control `add_header` inheritance from parent
`add_trailer_inherit`	`http`, `server`, `location`	1.29.3	Control `add_trailer` inheritance from parent
`keepalive_min_timeout`	`http`, `server`	1.27.4	Minimum keep-alive connection lifetime
`listen ... multipath`	`server`	1.29.7	Enable MPTCP (RFC 8684)
`proxy_pass_trailers`	`location`	1.27.2	Pass HTTP trailer fields from backends
`ssl_ech_file`	`server`	1.29.4	Encrypted Client Hello support
`ssl_key_log`	`http`, `server`	1.29.1	TLS key logging for debugging
`ssl_certificate_cache`	`http`, `server`	1.27.4	Explicit certificate caching control

New Variables

Variable	Since	Description
`$request_port`	1.29.3	Port from the request line
`$is_request_port`	1.29.3	Whether the port is explicitly specified in the request
`$ssl_sigalg`	1.29.3	TLS signature algorithm used by server
`$ssl_client_sigalg`	1.29.3	TLS signature algorithm used by client

Formerly nginx-plus-only Features Now in Open Source

Three major features previously exclusive to nginx-plus are now available. For full details and all variants, see references/upstream-and-load-balancing.md.

Sticky Sessions (1.29.6)

Cookie-based session affinity (most common pattern):

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;
    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

Three methods: cookie (client-side cookie), route (maps to existing session IDs), learn (server-initiated sessions). The route and drain parameters on the server directive are also now available.

DNS-based Upstream Resolution (1.27.3)

upstream backend {
    zone backend_zone 64k;  # required for resolve
    server backend.example.com resolve;
    server backend.example.com service=http resolve;  # SRV records
    resolver 10.0.0.1 valid=30s;
}

A shared memory zone is required when using resolve.

HTTP/2 Proxying to Backends (1.29.4)

proxy_http_version now accepts 2 for HTTP/2 connections to upstream servers:

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

Requires the ngx_http_v2_module.

103 Early Hints (1.29.0)

New early_hints directive controls passing 103 responses from backends to clients:

map $http_sec_fetch_mode $early_hints {
    navigate $http2$http3;
}

server {
    location / {
        early_hints $early_hints;
        proxy_pass http://backend;
    }
}

The 103 response is passed only when all string parameters are non-empty and non-zero.

MPTCP Support (1.29.7)

server {
    listen 80 multipath;
    listen 443 ssl multipath;
}

Enables Multipath TCP (RFC 8684). Implicitly enables SO_REUSEPORT.

Header Inheritance Fix (1.29.3)

add_header_inherit and add_trailer_inherit control inheritance from parent contexts. Previously, defining any add_header in a child block silently dropped all parent headers — a long-standing footgun now fixable.

# Parent headers are now inherited even when child defines its own:
server {
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    location /api {
        add_header_inherit on;          # inherit parent add_header directives
        add_header X-API-Version "2.0"; # this no longer drops the parent headers
        proxy_pass http://backend;
    }
}

keepalive_min_timeout (1.27.4)

Sets a minimum time a keep-alive connection stays open, preventing premature closure during graceful shutdown or connection reuse:

keepalive_min_timeout 10s;  # default: 0

TLS Changes

TLSv1/TLSv1.1 disabled by default (1.27.3) — ssl_protocols defaults to TLSv1.2 TLSv1.3
ECH support (1.29.4) — ssl_ech_file directive, requires OpenSSL ECH feature branch
QUIC 0-RTT (1.29.1) — supported with OpenSSL 3.5.1+
ssl_key_log (1.29.1) — TLS key logging for Wireshark debugging
ssl_certificate_cache (1.27.4) — explicit certificate caching control

For full details, see references/tls-and-security.md.

Reference Files

references/upstream-and-load-balancing.md — Sticky sessions (cookie/route/learn), DNS-based upstream resolution, HTTP/2 proxying details
references/tls-and-security.md — ECH support, QUIC 0-RTT, TLS key logging, certificate caching, TLS variables
references/http-and-transport.md — 103 Early Hints, header/trailer inheritance, keepalive_min_timeout, MPTCP, proxy_pass_trailers, new variables

nginx-knowledge-patch