Less magic.
Smaller surface.
Boring on purpose.

Split before TLS termination.

The stream layer can inspect the ALPN offer in ClientHello without terminating TLS. This selects a candidate lane, not the negotiated protocol: the downstream H2 listener must independently reject HTTP/1.x. The terminating HTTP servers still receive the client address through the trusted PROXY-protocol boundary.

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.

Bind these internal lanes explicitly to loopback and restrict who can connect. PROXY protocol text is not authentication, and loopback does not authenticate local processes. In the common start, use real_ip_header proxy_protocol with set_real_ip_from limited to the trusted shunt address; grant no broad network trust. Local processes outside that trust boundary need an additional access boundary.

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 can consume maintained CIDR files. For claim-to-network matching, each generated entry must identify its provider (for example 192.0.2.0/24 googlebot;), not merely set a global 1. Separate generated lists cover providers such as Apple, Bing, DuckDuckGo, Google, OpenAI and Qwant; 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. Match the claim to that provider's network, not to the union of all crawler networks. Even a match is only an edge-policy signal, not authentication; a broader goodbot signal may still skip a weak heuristic.

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. Serialize updates and preserve the last-known-good include: if validation or the reload command fails, restore the on-disk file. The schematic below assumes an existing regular include in a root-controlled directory. Staging the entire set as one transaction is an additional improvement when you need all feeds to advance together. A successful reload command still needs operational verification that the intended configuration is active.

Make the Lua chain reviewable.

A compact dispatcher should validate the chain before running modules: reject malformed names and duplicates, use an explicit allowlist, check module return types and fail closed on load/runtime errors. The short outline below delegates chain validation to a helper; a fuller example appears later.

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. Real-IP normalization can run before a limiter even when its directive lives in another include; limit_req/limit_conn run in preaccess, access Lua later, try_files later again and log handlers last. Internal redirects can change the active location and rerun phases; named locations do not inherit sibling FastCGI, proxy or rate-limit directives.

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.

client_body_timeout and send_timeout bound gaps between operations, not total request duration. Periodic progress can keep an exchange alive; a total execution deadline needs a separate application or service contract. A small wire body also need not mean a small parser heap. Frontend limits reduce exposure but do not repair backend memory/state defects or establish PHP2Shell prevention.

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.

limit_req directives are inherited only when the current scope defines none; a location-specific limit replaces the inherited list rather than automatically adding to it. Restate every zone that should apply together. limit_conn has the same inheritance shape for its own directives.

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. A narrower budget may follow validated application session state and a canonical resource path. A raw incoming session-cookie value is only client-supplied input: missing or rotating values can bypass or reset such accounting unless validation and a separate cookie-independent ceiling address that gap.

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.

By default, a child scope that defines any add_header stops inheriting the parent list. Restate the required headers or use a consistent include. nginx 1.29.3+ also supports an explicit add_header_inherit merge policy; review duplicates before using it, especially CSP fields whose policies combine rather than replace one another. always controls status-code coverage, not inheritance.

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 handshake-rejecting default as well. An HTTP return 444 requires a completed handshake and does not replace TLS configuration: a QUIC default without certificates must explicitly reject the handshake.

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. An exception must not become a blind spot: traffic exempted from a heuristic still consumes resources and belongs in cost and health telemetry.

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. Validate the complete name list and resolve every module contract before calling any run() function; only then may a handled result stop execution. Reject duplicates and unexpected returns, and fail closed when evaluation fails. Module loading must be free of request-policy side effects. The ngx.ctx guard applies only to the current request context, not across internal redirects.

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. The examples use normalized boolean inputs; overlapping exception classes are additive, so satisfying another class must not revoke an already valid exception.

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. By default, nginx does not pass a non-idempotent request to the next server once it has been sent upstream; attempts before sending are a different case. Do not enable non_idempotent retries without an application idempotency or reconciliation contract. “The socket failed” is not proof that the upstream did nothing. Proxy read/send timeouts bound inactivity between I/O operations, not the total request or response duration; periodic traffic can keep the exchange alive.

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. This optional systemd illustration is not directly applicable to a SysV service and does not describe the operator’s actual confinement; use the mechanisms of the deployed service manager.

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. The report-to name needs a matching endpoint declaration, shown below. Verify receipt with the supported browsers before interpreting silence; reports can contain sensitive URLs, so restrict reader access and retention.