Provides knowledge of Nginx changes from 1.27.3 to 1.29.7: upstream keepalive defaults, sticky sessions, DNS resolve, HTTP/2 proxying, TLS defaults, and breaking changes. Use before configuring recent Nginx versions.
npx claudepluginhub nevaberry/nevaberry-plugins --plugin nginx-knowledge-patchThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Implements structured self-debugging workflow for AI agent failures: capture errors, diagnose patterns like loops or context overflow, apply contained recoveries, and generate introspection reports.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
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).
| 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 |
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;.
ssl_protocols now defaults to TLSv1.2 TLSv1.3. If you need legacy protocol support, set ssl_protocols explicitly.
| 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 |
| 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 |
Three major features previously exclusive to nginx-plus are now available. For full details and all variants, see references/upstream-and-load-balancing.md.
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.
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.
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.
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.
server {
listen 80 multipath;
listen 443 ssl multipath;
}
Enables Multipath TCP (RFC 8684). Implicitly enables SO_REUSEPORT.
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;
}
}
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
ssl_protocols defaults to TLSv1.2 TLSv1.3ssl_ech_file directive, requires OpenSSL ECH feature branchssl_key_log (1.29.1) — TLS key logging for Wireshark debuggingssl_certificate_cache (1.27.4) — explicit certificate caching controlFor full details, see references/tls-and-security.md.