DEV Community: Danila Vershinin

The nginx misconfigurations that fail silently

Danila Vershinin — Sun, 30 Aug 2026 00:39:45 +0000

Most nginx misconfigurations announce themselves. You typo a directive, nginx -t fails, you fix it. That feedback loop is fast and it works.

The dangerous ones are different. The config is valid. nginx -t passes. The server starts, serves traffic, logs nothing unusual. And the thing you configured is quietly not happening.

I maintain gixy-ng, a static analyzer for nginx configs. A growing share of its checks exist for exactly this category, because it turns out static analysis is the only practical way to catch a failure that produces no signal at runtime. Here are four worth knowing about.

1. OCSP stapling that staples nothing

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.pem;
    ssl_certificate_key /etc/ssl/example.com.key;

    ssl_stapling on;
    ssl_stapling_verify on;
}

Looks right. It does nothing.

OCSP stapling means nginx fetches the certificate's revocation status from the CA itself and attaches it to the handshake, so the client does not have to. To do that, nginx has to make an outbound request to a hostname. nginx does not use the system resolver for runtime lookups. It has its own, and it only exists if you configure it.

No resolver in scope means the hostname never resolves, the fetch never happens, and stapling is silently skipped. Your config test passes. Your clients go do their own OCSP lookups, which is the exact thing you turned stapling on to avoid.

resolver 127.0.0.1 valid=300s ipv6=off;
resolver_timeout 5s;

Use a local resolver or your cloud provider's internal DNS. Pointing this at 8.8.8.8 sends every internal lookup off your network in cleartext, which is its own problem.

Check it with:

echo | openssl s_client -connect example.com:443 \
        -servername example.com -status 2>/dev/null \
    | grep -A 17 'OCSP response'

Working stapling prints OCSP Response Status: successful. Broken stapling prints no response sent. Run it twice, since the first handshake after a reload usually goes out unstapled while the fetch happens in the background.

One caveat that catches people right now: Let's Encrypt stopped serving OCSP in August 2025. If your cert is from them, the fix is to remove ssl_stapling, not to add a resolver.

2. An allow list that allows everyone

location /admin/ {
    allow 10.0.0.0/8;
    allow 192.168.1.0/24;

    proxy_pass http://admin_backend;
}

ngx_http_access_module checks rules in order and stops at the first match. If nothing matches, access is granted.

So a request from an arbitrary internet address matches neither rule, falls off the end of the list, and gets served. The intent is obvious to a human reading it and completely invisible to nginx. Add deny all; after the allows and it works.

The subtler version bites harder. Access rules are inherited from an outer context only when the inner context defines none of its own. So a single allow inside a location discards the entire server-level rule set for that location, including its deny all:

server {
    allow 10.0.0.0/8;
    deny all;              # server-wide restriction

    location /metrics/ {
        allow 172.16.0.1;  # replaces the whole set above
        stub_status;       # /metrics/ is now public
    }
}

You added a rule to tighten access and made the endpoint public.

3. return answering before your access rules run

location /health {
    allow 10.0.0.0/8;
    deny all;

    return 200 "ok";
}

Everyone on the internet gets 200 ok. The access list is correct, complete, and never consulted.

nginx processes requests in ordered phases. return lives in the rewrite phase. allow and deny live in the access phase. Rewrite runs first, return terminates the request immediately, and the access phase never happens.

Position in the file is irrelevant. Moving return below deny all changes nothing, because nginx is not reading your block top to bottom at request time. This is the same root cause as "if is evil": directives from different modules run in different phases, in an order that has nothing to do with how you wrote the file.

The fix is to reach the canned response through an internal redirect, so the access phase gets a chance to run:

http {
    open_file_cache max=10000 inactive=60s;
    open_file_cache_errors on;

    server {
        location /health {
            allow 10.0.0.0/8;
            deny all;

            try_files /nonexistent @health;
        }

        location @health {
            return 200 "ok";
        }
    }
}

try_files runs in the content phase, after access has been evaluated, so a refused client gets its 403 before the internal redirect is considered. The open_file_cache lines are there because a bare try_files pays a filesystem lookup per candidate on every request, which gixy also flags. Fixing one finding by creating another is not a fix.

4. QUIC connections dying on every reload

This one is my favourite, in the way that a really good bug is a favourite.

quic_bpf on;
worker_processes auto;

http {
    server {
        listen 443 quic reuseport;
        listen 443 ssl;
    }
}

Three ingredients: quic_bpf on, reuseport on a QUIC listener, and more than one worker. Any one alone is fine. All three together, and after every nginx -s reload roughly half your QUIC connections are silently dropped.

quic_bpf exists for a good reason. QUIC connections survive an IP or port change by connection ID rather than by 4-tuple, so a migrated packet can land on the wrong worker. nginx attaches an eBPF program to the reuseport socket group that reads the connection ID and routes each packet to the right worker.

On reload, nginx starts fresh workers and retires the old ones, but the BPF socket map still holds entries pointing at workers that are shutting down. Packets for live connections get steered at sockets nobody is servicing. Those connections die. Clients time out and quietly fall back to HTTP/2 over TCP.

Nothing is logged. No error, no warning, no counter. Your HTTP/3 traffic share just sags after each reload. It is a known upstream issue (nginx/nginx#425) and unfixed in mainline.

Set quic_bpf off;. You lose optimal connection-migration routing and you stop losing connections. For nearly every deployment that is the right trade.

And if you reload to pick up renewed certificates, which with 90-day certs is most people, you are hitting this every couple of months at minimum.

Running it

pip install gixy-ng

Scan the config as nginx actually assembles it, not the file you happen to be editing. nginx -T dumps the whole thing with every include resolved, which catches problems that only exist once the pieces are combined:

nginx -T > nginx-dump.conf
gixy nginx-dump.conf

Useful flags:

gixy -l 2 nginx-dump.conf              # MEDIUM and above
gixy -f json nginx-dump.conf           # machine readable, for CI
gixy --nginx-version=1.29.8 conf       # also check your version against known CVEs

That last one is worth calling out. gixy is config-static and has no view of your binary, so the CVE check stays silent unless you tell it which version you are running. Given a version, it reports the CVEs that apply, and for config-triggered ones it only fires when the offending directives are actually present. A CVE in the mp4 module is not your problem if you never compiled it in.

In CI, the JSON output plus a non-zero exit on findings above your threshold is usually all you need to stop a regression reaching production.

Why static analysis for this

Every failure above shares a shape: valid syntax, successful start, no runtime signal. Testing does not catch them because there is nothing to observe. Monitoring does not catch them because the metric you would need is the absence of a thing you assumed was happening.

The only place the information exists is the configuration itself, sitting there, being read by something that knows what these directives are supposed to do together.

The full check reference, with what each finding means and how to fix it, is at gixy.org/checks. Source and issues on GitHub.

The official Amplify app is now on iPhone

Danila Vershinin — Wed, 22 Jul 2026 13:51:22 +0000

F5's hosted NGINX Amplify reached end of life on January 31, 2026. GetPageSpeed Amplify keeps the familiar agent and compatible API running, with monitoring for NGINX, Varnish, PHP-FPM, MySQL and websites.

Now it has an official iPhone app.

Uptime by GetPageSpeed uses the same Amplify account and data already collected by your agents. There is nothing new to install on your servers.

The native app lets you:

Browse every server and its current health
Open live NGINX and system metric graphs
Manage alert rules and webhooks
Receive real-time push notifications
Follow host and metric incidents with Live Activities
Monitor website uptime, response time and SSL certificates

It also includes home-screen widgets, passkeys and two-factor security settings. Existing Amplify users can install it and sign in immediately.

Read the full announcement or download Uptime on the App Store.

NGINX Abuse Guard Module: Auto-Ban Scanners and Bots

Danila Vershinin — Sun, 19 Jul 2026 17:06:05 +0000

Open your NGINX error log on any public server and you will see the same thing: a steady drip of 404s probing for /wp-login.php, /.env, /phpmyadmin, and a thousand other paths that do not exist on your site. A vulnerability scanner walking your tree is a wall of 404s. A bot rattling locked admin endpoints is a wall of 403s. A credential-stuffing run is a wall of failed logins. Legitimate visitors almost never generate a burst of errors, but abusers generate little else. That asymmetry is the entire signal the NGINX abuse guard module acts on, and most servers throw it away.

The usual tools do not act on it cleanly. A rate limiter such as limit_req shapes load by request volume, so it slows everyone during a flood and lets the offender back in the instant the rate eases. Tools like fail2ban read the error pattern correctly, but they live outside NGINX: they tail a log file, parse it on a delay, and shell out to the firewall, so the ban lands seconds or minutes after the damage. What you actually want is to read the status codes your server is already returning and evict the clients whose traffic is mostly failure, immediately, inside the worker.

That is exactly what the NGINX abuse guard module does. It watches the final response status of every request, keeps a small per-client score in shared memory, and the moment a client crosses a threshold of errors it earns a timed ban enforced at the NGINX preaccess phase, before any handler, file lookup, or upstream runs. There is no sidecar, no log shipper, and no scripting layer. The decision happens in compiled C in a few microseconds. This guide shows you how it works, how to install and configure it, and how to roll it out safely against live traffic.

How the NGINX Abuse Guard Module Works

The module reduces abuse detection to three moving parts, all of which live inside the NGINX worker. Understanding them makes every configuration choice below obvious.

A leaky, decaying score per client

Every client identity carries a single small number in a shared-memory zone. Each matching error response adds to that score, and the score continuously bleeds away at a rate of threshold ÷ interval per second. A short, sharp burst of errors pushes the score over the line and trips a ban; a slow trickle of the occasional 404 spread across hours never accumulates. Crucially, that score is one fixed-size record no matter how high you set the threshold, so a single modest zone comfortably tracks the tens of thousands of distinct source addresses a botnet throws at you.

Counting at the header filter, deciding at preaccess

The module hooks two points in the request lifecycle. A header filter inspects the final response status of each request and updates the offending client's score. Separately, the preaccess phase checks whether the current client is already banned. Because preaccess runs before routing, static-file handling, and upstream proxying, a banned client is turned away at the cheapest possible point: NGINX never spends a cycle serving the request it is about to reject.

A privacy-correct refusal

When a banned client returns, it receives 429 Too Many Requests by default (you choose the code). The response carries a Retry-After header telling honest clients when to come back, and a Cache-Control: private, no-store header so that no shared cache or CDN can ever store one client's ban page and serve it to another. Identities are folded into a fixed-size digest before they are stored, so keying on something large like $request_uri or a header costs exactly as much memory as keying on a plain IP address.

Installation

Abuse Guard ships as a precompiled, signed dynamic module from the GetPageSpeed repository, so there is no build toolchain to install.

RHEL, CentOS, AlmaLinux, Rocky Linux, Amazon Linux

Install the NGINX abuse guard module from the GetPageSpeed RPM repository:

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-abuse-guard

Then load the module by adding this line at the top of /etc/nginx/nginx.conf, in the main context before any http {} block:

load_module modules/ngx_http_abuse_guard_module.so;

Debian and Ubuntu

First, set up the GetPageSpeed APT repository, then install from the APT module page:

sudo apt-get update
sudo apt-get install nginx-module-abuse-guard

On Debian and Ubuntu, the package handles module loading automatically. No load_module directive is needed.

On either platform, confirm the configuration is valid before reloading:

sudo nginx -t

Quick Start

A working policy is two directives. Declare one shared-memory zone in the http context, then switch enforcement on wherever abuse arrives:

load_module modules/ngx_http_abuse_guard_module.so;

http {
    abuse_guard_zone zone=clients:10m;     # one shared-memory zone

server {
        location / {
            abuse_guard zone=clients;      # enforce here
        }
    }
}

sudo nginx -t && sudo systemctl reload nginx

With nothing but a zone name and size, those defaults ban any single IP that returns 100 403 or 404 responses inside a 5-minute window, and the ban holds for one hour. Every one of those numbers is tunable, as the reference below shows.

Directive Reference

The module is four directives: one declares a policy, the rest apply it, exempt trusted clients, and optionally share bans across machines. Everything documented here is verified against the module source, so you can rely on the contexts and defaults exactly as listed.

abuse_guard_zone

Context: http. Carves out one shared-memory zone and sets the policy that governs it. The zone name and size are the only required parameters; sensible defaults fill in the rest.

abuse_guard_zone zone=clients:10m
                 key=$binary_remote_addr
                 statuses=403,404
                 interval=300s
                 threshold=100
                 block=60m;

Parameter	Default	Description
`zone`	(required)	The policy name (referenced by `abuse_guard`) and the shared-memory size, e.g. `clients:10m`. About 10 MB tracks on the order of a hundred thousand live clients.
`key`	`$binary_remote_addr`	The expression that defines one client. Any NGINX variable. A request whose key resolves to an empty string is skipped entirely.
`statuses`	`403,404`	Which response codes count as errors. Individual codes, ranges, or a mix, e.g. `statuses=401,403,404,500-599`.
`interval`	`300s`	The window the score decays over. A burst inside it trips a ban; a slow trickle never accumulates.
`threshold`	`100`	How many errors within the window cross the line, up to 1024.
`block`	`60m`	How long a tripped client stays locked out.
`inactive`	`max(1h, interval, block)`	How long a dormant client lingers in memory before reclamation. Any explicit value must be at least as large as both `interval` and `block`.
`redis`	`off`	Set `on` to replicate this zone's bans across a fleet (see below).
`persist`	(none)	A file path to snapshot bans into so they survive a restart.
`persist_interval`	`5s`	How often the snapshot is rewritten.
`persist_secret`	(none)	A hex key that signs the snapshot with HMAC-SHA256, so a tampered file is rejected rather than loaded.

Why 5xx is left out by default: a server error is usually your side's doing, and counting it would let one flaky backend get innocent visitors banned. Add statuses=403,404,500-599 only when you deliberately want to act on clients that trigger server errors.

abuse_guard

Context: http, server, location. Applies a declared policy. Name the zone to switch enforcement on; write abuse_guard off; in a nested scope to switch it back off for that scope.

location /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
}

Parameter	Default	Description
`zone`	(required)	The zone (declared with `abuse_guard_zone`) whose policy applies here.
`status`	`429`	The code a banned client receives, anywhere in `400` to `599`.
`dry_run`	`off`	Set `on` to observe without enforcing: the verdict is logged but no ban is written.
`log_level`	`notice`	How loudly to log each decision: `info`, `notice`, `warn`, or `error`.

abuse_guard_allow

Context: http, server, location. Repeatable and inherited downward. Listed clients are never counted and never banned. Matching is on the true connection address, so it cooperates with realip.

abuse_guard_allow 127.0.0.0/8;
abuse_guard_allow 10.0.0.0/8 192.168.0.0/16;

abuse_guard_redis

Context: http. Points the server at one Redis or Valkey instance for fleet-wide ban replication. Pair it with redis=on on the zone you want shared.

abuse_guard_redis host=10.0.0.5 password=secret;   # tls://host for TLS
abuse_guard_zone  zone=clients:10m redis=on;

Parameter	Default	Description
`host`	(required)	The Redis or Valkey host. Prefix with `tls://` to connect over TLS.
`password`	(none)	Authentication password, if the server requires one.
`port`	`6379`	The server port.
`db`	`0`	The logical database number.
`prefix`	`ag_`	Key and channel prefix, so several services can share one Redis safely.
`timeout`	`100ms`	Connection and command timeout for the out-of-band replication path.

Variables

The module exposes exactly three variables, which you can write to your access log or use in a map:

Variable	Value
`$abuse_guard_status`	The verdict for this request: `BYPASSED`, `PASSED`, `COUNTED`, `BLOCKED`, or `DRY_RUN`.
`$abuse_guard_count`	The error count currently attributed to this client.
`$abuse_guard_blocked_until`	The Unix timestamp when the ban lifts, or `0` if the client is not banned.

A custom log format makes the module's decisions visible while you tune it:

log_format guard '$remote_addr "$request" $status '
                 'guard=$abuse_guard_status count=$abuse_guard_count';

access_log /var/log/nginx/access.log guard;

Security Hardening Use Cases

Blocking vulnerability scanners and 404 floods

This is the case the defaults are built for. An automated scanner requests hundreds of nonexistent paths in quick succession, and every miss is a 404. Enforce the default policy site-wide and the scanner bans itself within seconds of starting, while a real visitor who fat-fingers one URL never comes close to the threshold:

http {
    abuse_guard_zone zone=scanners:10m statuses=404 threshold=40 interval=60s block=30m;

server {
        location / {
            abuse_guard zone=scanners;
        }
    }
}

Brute-force protection on login and admin endpoints

Credential-stuffing and admin-probing bots produce 403s and failed logins. Scope a stricter policy to the endpoints they target, so a handful of failures is tolerated but a sustained run is locked out, without affecting the rest of the site:

location = /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
    # ... your usual fastcgi_pass / proxy_pass ...
}

Exempting authenticated users with a map

Because a request whose key resolves to an empty string is skipped, a map lets you track anonymous visitors by IP while leaving logged-in users untouched. Here, requests that carry a session cookie produce an empty key and are never scored:

map $cookie_sessionid $abuse_key {
    ""      $binary_remote_addr;   # anonymous: key on IP
    default "";                    # logged in: skip entirely
}

http {
    abuse_guard_zone zone=clients:10m key=$abuse_key;
}

Protecting verified search crawlers

A search-engine crawler grinding through stale URLs can rack up 404s through no fault of yours. Allowlist the published crawler ranges so they are never counted. Because matching is on the real connection address, this also cooperates with realip when you run behind a CDN:

abuse_guard_allow 66.249.64.0/19;   # example Googlebot range
abuse_guard_allow 157.55.0.0/16;    # example Bingbot range

Rolling out safely with dry_run

Never flip a new ban policy straight to enforcing on production traffic. Run it in observation mode first: dry_run=on records every ban it would issue, in the log, without writing any state. You can even run a dry-run location next to an enforcing one on the same zone, calibrate the threshold against real traffic, then flip it live once the numbers look right:

location / {
    abuse_guard zone=clients dry_run=on log_level=warn;
}

Watch the log for the bans it reports, confirm no legitimate client is caught, then remove dry_run=on.

Fleet-Wide Bans with Redis or Valkey

Behind a load balancer, a per-server ban is theatre: the attacker simply lands on a different node. Abuse Guard closes that gap without ever putting Redis in the request path. Point every node at one Redis or Valkey instance and set redis=on on the zone:

http {
    abuse_guard_redis host=10.0.0.5 password=secret;
    abuse_guard_zone  zone=clients:10m redis=on;

server {
        location / {
            abuse_guard zone=clients;
        }
    }
}

SELinux: on enforcing systems (RHEL, Rocky Linux, AlmaLinux) the kernel blocks NGINX from opening the connection to Redis until you permit it once with setsebool -P httpd_can_network_connect 1. Skip this and replication silently does nothing while local enforcement carries on as normal.

Each node still decides locally and counts locally. The instant a node issues a ban, it broadcasts that one fact to the cluster and records a durable copy; every other node imports it within milliseconds, and a node that was offline reconciles the moment it reconnects. Because enforcement is always served from each node's own in-memory state, a visitor's request never waits on a network round-trip. Redis here is a one-way alarm bell, not a shared ledger consulted per request, so a slow or missing Redis can never add latency to your traffic. Run it on a private network and treat write access as privileged: anything that can write to it can issue bans.

Bans That Survive a Restart

Point a zone at a file and active bans are snapshotted on an interval and restored at startup, so a reload or a reboot does not hand every attacker a fresh slate:

abuse_guard_zone zone=clients:10m
                 persist=/var/lib/nginx/abuse_guard/clients.state
                 persist_secret=00112233445566778899aabbccddeeff;

The snapshot is integrity-checked and written so that a crash can never leave a torn file. With persist_secret set, it is also signed with HMAC-SHA256, so a tampered file is rejected rather than trusted. Keep the directory readable only by the NGINX worker user.

Abuse Guard vs limit_req and fail2ban

NGINX already ships rate limiting, and most servers already run fail2ban, so it is worth being precise about where Abuse Guard fits rather than presenting it as a replacement for either.

	limit_req	fail2ban	Abuse Guard
Signal	Request rate	Log patterns	Response error rate
Action	Throttle / delay	Firewall ban	Timed in-worker ban
Where it runs	In NGINX	Out of process	In NGINX
Reaction time	Immediate	Log-tail delay	Immediate
Best at	Shaping load	Host-wide bans across services	Evicting error-heavy clients

Use a rate limiter to shape load and protect capacity. Use fail2ban for host-wide bans that span SSH, mail, and other services. Use Abuse Guard for the specific job neither does well: reading the errors NGINX is already returning and evicting the clients defined by them, in the same worker, on the request itself. The three layer cleanly. A common production stack runs limit_req for burst control and Abuse Guard for eviction in the same location.

Performance Considerations

Abuse Guard is engineered to make abuse cheap to reject and good traffic free to serve. Three properties matter in production:

Rejection is the cheapest outcome. A banned client is turned away at the preaccess phase, before routing, file lookups, or upstream connections, so the more an attacker hammers you the less each request costs.
Memory is fixed per client. Each tracked identity is one small, constant-size record regardless of threshold, so a single 10 MB zone tracks roughly a hundred thousand clients. That is what lets one zone absorb a botnet.
Optional dependencies fail open. Clustering and signed snapshots are best-effort by design. If Redis or the disk misbehaves, enforcement quietly carries on from local memory and your traffic is never held hostage to a dependency.

Troubleshooting

Symptom	Cause and fix
`nginx -t` reports "unknown directive abuse_guard_zone"	The module is not loaded. Confirm `load_module modules/ngx_http_abuse_guard_module.so;` is in the main context on RHEL-based systems, and that the package is installed: `ls /usr/lib64/nginx/modules/ngx_http_abuse_guard_module.so`.
Bans never trip	The score decays at `threshold ÷ interval` per second. If errors arrive slower than that, the score never builds. Lower `threshold` or shorten `interval` for the burst you want to catch.
A client is never counted	Its `key` may resolve to an empty string (skipped by design), or it may match an `abuse_guard_allow` range. Check both.
Wrong client is banned behind a CDN	You are keying on the proxy address. Resolve the real client with `realip` first, then key on `$binary_remote_addr`.
`dry_run` bans nothing	That is correct: `dry_run=on` logs the verdict but never writes a ban. Check the log for the bans it reports, then remove `dry_run=on` to enforce.
Redis replication does nothing on RHEL or Rocky Linux	SELinux is blocking the outbound connection. Allow it once with `setsebool -P httpd_can_network_connect 1`, then reload NGINX. Local enforcement is unaffected either way.
A `return` in the same location appears to bypass the guard	A `return` directive can short-circuit request processing. Place enforcement where it runs before any short-circuit, or in a parent scope.

When you run behind a CDN or reverse proxy, never trust a raw X-Forwarded-For. Let realip resolve the true client first:

set_real_ip_from 10.0.0.0/8;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Conclusion

A tuned Abuse Guard policy only stays correct until someone touches the config. NGINX upgrades, module updates, and routine edits quietly reintroduce the very gaps you just closed, and a ban rule that silently stops matching is worse than none. GetPageSpeed Amplify runs scheduled gixy scans across every host and ties findings to live NGINX runtime metrics. Drop-in compatible with the deprecated nginx-amplify-agent (EOL January 2026).

The NGINX abuse guard module turns the errors your server already returns into an automatic, self-calibrating defense. It reads the one signal abusers cannot hide, decides in microseconds inside the worker, and evicts offenders with a real timed ban instead of a throttle that lets them straight back in. With dry_run for safe rollout, a map-driven key for surgical scoping, optional fleet-wide replication, and bans that survive a restart, it covers the timed-ban niche that neither limit_req nor fail2ban fills. Pair it with the NGINX delay module to tarpit slow probers, the NGINX WAF module for payload inspection, or ModSecurity for NGINX for full rule-based filtering.

Abuse Guard is available as a pre-built package from the GetPageSpeed RPM repository and the GetPageSpeed APT repository. For licensing, volume deployments, or a hand getting set up, contact us.