Agent Skills: Nginx Knowledge Patch (1.27.3 – 1.29.7)

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