NGINX HTTP/3 (QUIC) Reverse-Proxy Setup Prompt
Generate a correct, production-ready HTTP/3 + QUIC server block for an existing NGINX reverse proxy — UDP 443 listeners, Alt-Svc advertisement, congestion/retry settings, and TLS 1.3 — without breaking your working HTTP/2 fallback.
- Target user
- Engineers enabling HTTP/3 on a TLS-terminating NGINX in front of an app or CDN origin
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior edge/infrastructure engineer who has shipped HTTP/3 (QUIC) on NGINX in production. You know that HTTP/3 rides on UDP, that clients only discover it via `Alt-Svc`, and that a broken HTTP/3 config must never take down the working HTTP/2 path. You comment every non-obvious directive and you never assume a module is compiled in.
I will provide:
- My current NGINX version and how it was built (distro package, `nginx -V` output, or custom build): [PASTE `nginx -V`]
- The vhost(s) getting HTTP/3 and their TLS cert/key paths: [DESCRIBE]
- Whether this NGINX terminates TLS or passes through: [TERMINATES / PASSTHROUGH]
- Firewall / security-group control over UDP 443: [DESCRIBE]
- CDN or load balancer in front, if any: [DESCRIBE]
Do this:
1. **Prerequisite check first.** Before any config, tell me exactly how to confirm QUIC support: `nginx -V 2>&1 | grep -o with-http_v3_module` and an OpenSSL/QUIC-TLS note. If the binary lacks `http_v3_module`, stop and explain the build/upgrade path — do not emit a config that will fail `nginx -t`.
2. **Dual-stack listeners.** Produce a `server {}` that keeps `listen 443 ssl;` + `http2 on;` for TCP **and** adds `listen 443 quic reuseport;` for UDP. Explain that `reuseport` must appear on exactly one listener per address:port and why duplicating it errors.
3. **Alt-Svc advertisement.** Add `add_header Alt-Svc 'h3=":443"; ma=86400' always;` and explain that without it, no browser will ever upgrade to HTTP/3 — clients start on HTTP/2 and only switch on the next request.
4. **TLS requirements.** Confirm TLS 1.3 (`ssl_protocols TLSv1.3;` at minimum for the QUIC listener context), and note QUIC requires it. Keep TLS 1.2 available on the TCP listener for older clients.
5. **QUIC tuning.** Set sensible `quic_retry on;` (address-validation / anti-amplification) and note `quic_gso` and `http3_stream_buffer_size` as optional tunables with what each affects. Do not over-tune — call out which defaults are fine.
6. **Firewall + MTU reality.** Remind me to open **UDP** 443 (not just TCP) end to end, and warn about UDP being blocked or rate-limited by upstream firewalls/CDNs, and about path-MTU/fragmentation pitfalls.
Output: (a) the complete, commented `server {}` block with both listeners, (b) the exact `nginx -V` grep and `nginx -t` validation commands, (c) a verification recipe using `curl --http3` and Chrome's `chrome://net-internals` / an `Alt-Svc` header check, and (d) a rollback note: HTTP/3 is additive — removing the `quic` listener and `Alt-Svc` header cleanly reverts clients to HTTP/2. Treat the config as a reviewable artifact: validate with `nginx -t` and reload, never edit the live prod file in place.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
HTTP/3 fails in a handful of predictable ways, and this prompt front-loads every one of them. The most common is a binary that was never built with http_v3_module, so the prompt refuses to emit config until you have grepped nginx -V — turning a confusing nginx -t failure into a clear prerequisite check.
The second trap is transport: HTTP/3 is UDP, and engineers routinely open only TCP 443, then watch handshakes time out with no useful log line. By making UDP 443 and the reuseport single-listener rule explicit requirements, the prompt stops the two errors that cause most “HTTP/3 just doesn’t work” tickets.
Finally, HTTP/3 is discovery-based: without an Alt-Svc header, no browser ever upgrades, so the feature looks broken even when the listener is perfect. Requiring the header plus a concrete curl --http3 and Alt-Svc verification step means you can prove the upgrade actually happens — and because the whole change is additive, the built-in rollback note keeps your working HTTP/2 path safe the entire time.
Related prompts
-
NGINX CORS & Preflight Proxy Prompt
Get correct, secure CORS handling in NGINX for a reverse-proxied API — OPTIONS preflight, Access-Control-* headers, credentials, and per-origin allow-listing — without the classic duplicate-header and wildcard-with-credentials footguns.
-
NGINX auth_request Subrequest SSO Prompt
Design a correct `auth_request` gateway that offloads authentication to an external SSO/auth service — forwarding the right headers, handling 401/403 vs 5xx distinctly, and passing identity back to your app — instead of a fragile snippet that leaks unauthenticated traffic on the auth service's bad day.
-
NGINX Dynamic Upstream DNS Resolution Prompt
Make NGINX re-resolve backend DNS at runtime instead of caching it forever at startup — configure the resolver directive with variables in proxy_pass (or upstream re-resolution) — so proxying to cloud services, Kubernetes, or autoscaled targets stops sending traffic to dead IPs.
-
Configure NGINX TLS, HSTS & OCSP Stapling Prompt
Build a modern, A-grade NGINX TLS configuration with correct protocol/cipher selection, OCSP stapling, session settings, and a safe HSTS rollout, then verify it against a real handshake.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.