Less magic.
Smaller surface.
Boring on purpose.

Split before TLS termination.

The stream layer can inspect ALPN from ClientHello without terminating TLS. That lets the HTTP servers remain normal TLS endpoints while still receiving distinct protocol classes and the original client address.

Separate transport policy from application policy.

A useful file split is common-start → lane-specific policy → common-end. The common start restores the trusted client address and applies global request invariants; the lane file contains protocol-specific controls; the common end defines exact application endpoints, Lua access policy, static handling and logging.

Protocol support is not a protocol guarantee.

Browsers and modern crawlers may prefer h2 or h3, while inspection tools, provider control planes and legacy clients can still arrive over H1. Keep the compatibility exception conjunctive: protocol + verified network/client class + expected host + allowed method/route.

Pull network evidence from the provider, not from a blog post.

nginx geo maps are a convenient way to consume maintained CIDR files. In production I use separate generated files for public crawler networks such as Apple, Bing, DuckDuckGo, Google, OpenAI and Qwant, then validate the whole config before reload.

Require both when the exception depends on crawler identity.

A public CIDR says where the request came from. The user agent says which crawler role it claims. For stronger protocol or compatibility exceptions, require both. For lower-stakes heuristic exemptions, a separate broader goodbot signal can remain intentionally less strict.

Keep operator, crawler and service exceptions independent.

Do not make one global $whitelist mean “skip security.” Use separate variables and combine them only where the endpoint actually needs the exception. Documentation-range addresses are used below deliberately.

Automate the boring part, then fail closed on deployment.

Generated crawler lists should come from official feeds, be rendered into deterministic nginx include files, and be replaced per-file atomically. The updater should stop on fetch or parse errors and reload only after nginx -t succeeds. Staging the entire set as one transaction is an additional improvement when you need all feeds to advance together.

Make the Lua chain reviewable.

A compact dispatcher can normalize an ordered chain, reject duplicates, require an explicit module allowlist, verify the module contract and fail closed on load/runtime errors. That is much easier to reason about than scattered access_by_lua_block fragments.

Keep cheap classification in nginx variables.

Large map/geo sets are lazy-evaluated by nginx. They are excellent for composing protocol, path, CIDR and method signals into a small number of policy variables. Lua should receive the already-classified request rather than reimplementing the whole edge parser.

Debug the weird request, not the whole internet.

Detailed header/body capture is operationally useful, but expensive and sensitive. Derive a small $is_deep class from route/policy signals, capture only there, truncate bodies, and pass the minimum context through ngx.ctx to the log phase.

Log the reason class, not only the status code.

Separate streams for normal traffic, verified crawlers, rate limits, high-confidence sinks and deep diagnostics make investigations faster. A higher-confidence event can suppress duplicate lower-value log lines so one request does not masquerade as five incidents.

Review the effective request path, not the include tree.

A common split such as common-start → lane policy → common-end improves ownership, but the runtime still follows nginx phases. In a real edge, real-IP normalization can execute before a limiter even if its directive lives in another include; limit_req/limit_conn run in preaccess; access Lua runs later; try_files later again; log handlers run last.

Compose capabilities instead of building a magic whitelist.

Keep lane admission, heuristic exemption, resource budgeting and application authorization as different outputs. This makes policy reviewable: one signal can relax one heuristic without mutating unrelated controls.

Keep the default envelope finite.

Hide the nginx version, bound headers and bodies, and set finite read/write timeouts. Large uploads or long-running upstreams should get narrowly scoped exceptions instead of globally relaxed defaults.

Prefer current protocols; make replay a conscious choice.

TLS 1.2 + 1.3 remains a sensible compatibility baseline. Keeping 0-RTT disabled is conservative unless the application and every relevant request path are designed around replay semantics.

Do not serve an application by accident.

A dedicated TLS default server can reject handshakes for names you do not host. This is cleaner than letting an unknown SNI select whichever application server happens to be first.

Static means GET and HEAD.

For a truly static vhost, other methods are noise. The return-only conditional below is intentionally simple; dynamic applications should define their method policy per endpoint instead.

Do not make dotfiles discoverable by default.

Reject hidden paths unless you deliberately publish one. If you use ACME HTTP-01 or a well-known metadata path, carve that path out explicitly rather than weakening the general rule.

Rate-limit work, not identities.

nginx has native request and connection budgets. Start with broad, measurable ceilings and narrow them only where the workload justifies it. If nginx sits behind another proxy, establish the trusted real-client address first or an IP-keyed limit is meaningless.

For HTTP/2 and HTTP/3, remember that nginx counts each concurrent request as a connection for limit_conn.

Use empty keys to limit one operation, not the whole site.

A login or sign-up budget should normally count only those requests. Build the key from the request shape you care about and return an empty value for everything else. nginx does not account empty keys in the zone.

Key expensive work to the resource being abused.

Per-IP controls are useful coarse ceilings, but they are often the wrong identity model. For stateful applications, a tighter budget can follow a server-issued session plus a canonical resource path so rotating egress addresses do not reset the cost accounting.

The exact key is application policy. Keep it out of generic public examples if it would reveal bypass-sensitive internals.

Do not publish an authentication helper just because nginx can proxy it.

Subrequest-based authentication works well when the helper is reachable only from nginx. Keep the auth location internal and the service on loopback or a private Unix socket; the public application consumes only the allow/deny result.

Make the weird client the exception, not the global policy.

Payment providers, webhooks, monitoring agents and old package clients sometimes need a protocol, method or timeout that normal browser traffic does not. Keep the exception on the exact route and preserve the stricter default everywhere else.

Do not forward client claims as facts.

This example assumes nginx is the public edge and should overwrite client-supplied forwarding headers. In a real proxy chain, configure trusted proxies and real-IP processing first; only then preserve the chain you actually trust.

Use browser policy that matches the application.

nosniff and a deliberate referrer policy are low-drama defaults. HSTS is powerful but sticky: enable it only when HTTPS is genuinely permanent for that host. CSP and framing policy are application-specific and should be designed, not copied from a random checklist.

Log enough to explain a request.

JSON escaping, request IDs, protocol, status, latency and upstream timings make incident analysis much easier. Keep secrets, authorization material and full session state out of the default access format; use a separate protected debug path if you truly need deeper capture.

Fail closed on UDP/443 as deliberately as on TCP/443.

A TLS default server can reject unknown SNI before normal HTTP handling on TCP. HTTP/3 arrives on a separate QUIC listener, so give that socket its own default server and a cheap rejection path as well.

Advertise QUIC only where you actually operate it.

Keep Alt-Svc host-scoped rather than global, validate client addresses with QUIC Retry when appropriate, and verify the UDP path independently from the existing TCP/H2 path.

Security headers are application policy, not one global string.

Some headers make sense everywhere; CSP, cache policy and indexing often do not. A host map lets nginx keep a shared edge while emitting the policy that actually matches each application.

Keep a normal request stream and a cheap error mirror.

A compact all-request JSON log is useful for baselines. A second conditional log containing only 4xx/5xx requests gives incident tooling a smaller stream without changing enforcement or forcing verbose debug logging globally.

Use Lua as a small policy layer, not an unbounded second application.

For request classes that outgrow map and geo, a deterministic access-phase dispatcher keeps policy modules explicit. Run it once per request, allowlist module names, validate module contracts and fail closed if the policy engine itself cannot be evaluated.

Compatibility exceptions should be conjunctive, not hopeful.

If the public edge prefers newer protocols but a crawler or service still needs HTTP/1.1, verify the thing that justifies the exception. A crawler claim can require both an expected UA and a published network; an export client can require the exact export route plus its expected client shape.

Log the policy class that fired, not only the final status.

Separate low-volume streams for verified crawlers, explicit allowlists, rate-limit events and rejected policy classes make rotation review much faster. Lua can enrich only the deep-debug class in the log phase, so ordinary traffic stays cheap.

Reconstruct the upstream request instead of forwarding ambiguity.

Keep nginx and upstream software current, use one well-defined frontend path, strip the historical Proxy header, and set forwarding and hop-by-hop headers yourself. WebSocket upgrade headers belong only on the routes that actually upgrade. Turning off chunked transfer encoding globally is not a generic request-smuggling fix.

Do not let two routing names disagree silently.

A fail-closed default server handles unknown SNI. For applications that require one canonical public name, a second policy can also reject a request whose TLS name and HTTP Host do not belong to the same allowed pair. Canonical redirect hosts should be modeled deliberately rather than accidentally caught by this check.

Oversized and invalid headers should fail at the edge.

Keep header buffers finite and preserve strict parsing unless the application has a documented reason not to. nginx uses some request-line and header directives during virtual-server selection, so changing them per host can be less local than it looks.

Multipart ranges are a feature, not a birthright.

Large static objects may need byte ranges for media players or resumable downloads. Most HTML/API responses do not need arbitrarily many ranges. Limit or disable them where the workload does not use multipart range responses.

Key every representation dimension — or bypass the cache.

If authenticated state, cookies, language or request headers can change the response, either include the relevant dimension in the cache design or do not cache that request. Keep the cache key readable and explicit; never let an untrusted Host or a hidden personalization input create shared output for another user.

Dynamic upstream DNS needs an explicit trust anchor.

Runtime DNS resolution is useful for changing service addresses, but it moves routing decisions into DNS. Point nginx at a secured local or private resolver, use a bounded cache lifetime appropriate for the environment, and keep resolution timeouts short enough that DNS failure does not become request pile-up.

Transport uncertainty must not become a double side effect.

Keep connect/read/send timeouts finite and be conservative with retries. nginx does not retry non-idempotent requests unless configured to do so; keep it that way unless the application has a real idempotency key or provider reconcile contract. “The socket failed” is not proof that the upstream did nothing.

Large uploads need a disk contract, not merely a bigger number.

nginx writes bodies larger than its buffer to temporary files. Put those files on a deliberately sized path with restrictive ownership; on Linux, a dedicated filesystem with nodev, nosuid and usually noexec can reduce the consequences of an application mistake. Increase limits only on routes that really upload.

Reject impossible probes before redirects and upstream bootstrap.

A very small list of paths that cannot exist on the service — exposed VCS metadata, environment files or a framework the application does not run — can be rejected at the edge. Keep this list short and high-confidence. It is a cost sink, not a replacement for application security.

Uniform denial can be more useful than a faster denial.

When nginx itself fronts password, subrequest, JWT or OIDC authentication, auth_delay can make 401 timing less informative. It is not password hashing and it is not rate limiting; it is one small way to avoid turning rejection latency into an oracle.

Constrain the service after the config is correct.

nginx already drops worker privileges, but the service manager can narrow the process view further. Treat these as deployment policy, not copy-paste defaults: certificate loading, dynamic modules, Unix sockets, log paths and temp directories all need to be included deliberately.

Stage browser policy before turning it into an outage.

For applications with a non-trivial CSP, start new policy in Content-Security-Policy-Report-Only, inspect violations, then enforce. Treat the report endpoint itself as untrusted input: body limits, rate limits and retention still apply.