DEV Community: Danila Vershinin

Backporting the PHP2Shell fix to PHP 5.6 and 7.0 on CentOS 7

Danila Vershinin — Thu, 22 Oct 2026 06:15:28 +0000

PHP2Shell (CVE-2026-109618 and CVE-2026-109619) is a pair of unauthenticated RCEs in PHP, rated CVSS v4.0 9.2. The PHP project fixed 8.2 and newer, published source-only backports for 7.4, 8.0 and 8.1, and nothing for 7.3 and older. CentOS 7 boxes still running Remi's PHP 5.6 or 7.0 had no binary fix anywhere. Here is how we ported it and how we convinced ourselves the port is right.

What the upstream fix actually does

Both bugs share a root cause: PHP's out-of-memory handling is a longjmp (zend_bailout()). When that fires in the middle of request startup, say while rfc1867.c is parsing a multipart body, request state is left half built. Cleanup then trusts it (CVE-2026-109618), or a freed pointer survives into the next request on the same worker (CVE-2026-109619).

The security team's minimal backport for EOL branches (php-src branch PHP-7.4-CVE-2026-109618-109619, commit 712e60f9) does three things:

Stop unwinding on allocator failure. A new zend_mm_safe_error_ex() prints the error and calls _exit(1) instead of bailing out. Every overflow site in zend_alloc, zend_hash, the string-concat VM handlers and friends routes through it.
Reset request globals on shutdown. NULL out freed request strings in SAPI.c, clear http_globals, reset user error and exception handlers, the handler stacks and the object store at the end of shutdown_executor().
Close the known entry points. Header whitelisting and de-duplication in rfc1867.c, and the session upload-progress hook disabled outright.

Porting to 7.3 and 7.0

7.3 is close enough to 7.4 that most hunks applied cleanly. The interesting differences:

7.3 has no pre-free !fast_shutdown block in zend_execute_API.c, so the handler reset has to go where 7.4 runs it on the fast-shutdown path, before the object store is freed.
7.3's in-place CONCAT extend path had no overflow check at all. We added the upstream check, then regenerated zend_vm_execute.h with zend_vm_gen.php (first proving the generator is byte-identical on the unpatched tree). The result has 34 safe-exit sites, the same as upstream 7.4.
Remi's base already carries the CVE-2023-0662 max_multipart_body_parts patch, so those rfc1867.c hunks were dropped instead of duplicated.

7.0 needed real adaptation:

7.0 has no _zend_new_array_0(), so array_init_singleton() became array_init() plus nTableSize = 1, the same table shape upstream creates.
7.0 has no fast-shutdown branch and destroys the handler stacks inside a zend_try. The reset runs once at the very end of shutdown_executor(), after every destroy.
7.0's estrdup overflow sites passed an int to %zu; we used upstream's format.
7.0 is C89, so the session hook is disabled with || 1 rather than true.

PHP 5.6: start from a vendor port, then fix it

For 5.6 we started from a commercial vendor's published 5.6 adaptation and audited it hunk by hunk against upstream 7.4 and our own 7.0 port. It was right about the allocator, rfc1867.c, SAPI.c and the session hook. It missed part of the shutdown reset: it cleared error_handling and exception, but not the user error and exception handlers, the three handler stacks, or the object store. In 5.6, zend_ptr_stack_destroy() leaves elements dangling, which is exactly the stale-state shape CVE-2026-109619 exploits. We added the missing resets.

A public community patch set for 5.6 touches only the allocator, session and rfc1867.c, and omits the shutdown resets entirely.

Proving it

Each build runs through the same harness in a pristine CentOS 7 container:

Install the exact Remi NEVRAs the host has today.
Run both PHP2Shell probes and require them to reproduce. The out-of-memory probe exits 255 and the upload-progress hook runs.
yum upgrade to our build. Require both probes to fail: the OOM probe exits 1 and the hook never runs.
Run the full phpt suite against the baseline. The only accepted differences are nine tests whose behaviour changes by design (eight rfc1867 tests and bug45392).
Diff php -m (including PECL and ionCube), check configuration is preserved and PHP-FPM serves after an OOM request.
yum downgrade back to Remi and confirm it works.

Builds that pass went to production the next day on PrestaShop 1.6 and Magento 1 servers with nothing more than a PHP-FPM restart.

The trade-off

With the fix, hitting memory_limit kills the worker immediately: no shutdown functions, no flushed output. Upstream made the same call for its EOL backports. If your code relies on a shutdown handler to log memory exhaustion, it will go quiet.

Install

The packages are free in the GetPageSpeed repository and replace Remi's in place:

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum --enablerepo=getpagespeed-extras-php70 upgrade 'php-*'   # or php56, php80
systemctl restart php-fpm

PHP 7.3 (Remi SCL), PHP 8.4.27, and the full per-version details are in the PHP2Shell on CentOS 7 guide.

Find Linux Packages Across Repositories with pkgdex

Danila Vershinin — Sun, 18 Oct 2026 17:44:27 +0000

Installing a package is usually easy once you know its name and which repository provides it. Finding that combination can take longer, especially when you work across several Linux distributions.

Does the package exist for your distribution release? Is there an ARM build? Which package contains a particular executable? Is the result from the distribution itself or a third-party publisher?

pkgdex puts those questions into a searchable package index. I built pkgdex and run GetPageSpeed, whose repositories are included alongside distribution repositories and other publishers. Here is a practical way to use it, starting with NGINX.

Start with a package name

Open the search results for nginx.

The results are grouped by distribution and release. Each row identifies the repository, architecture, package filename, and description. That makes it possible to see where a package comes from before opening its details.

A name search can also return related packages. For example, the NGINX results include modules and configuration packages as well as the server itself. Read the package name and description rather than assuming every match installs the same thing.

Start with the distribution release you actually run, then check the architecture. An x86_64 result and an aarch64 result are different builds. A familiar package name does not make a build for another distribution interchangeable with yours.

If you prefer browsing first, the home page lists distributions and repositories. The wider index also includes BSD, macOS, and Flatpak sources, but this walkthrough stays with Linux packages.

Inspect the package before installing

Follow a package filename to its detail page. For a concrete example, this NGINX package for openSUSE Leap 16.0 shows its version, architecture, repository, license, dependencies, provided capabilities, and file list.

The file list answers questions that a short package description cannot: where is the executable, which configuration paths are included, and does this build ship the module you need?

The page also provides installation guidance and a download link. Treat it as information about that particular build. For an actual installation, use your distribution's package manager with the appropriate repository configured, so it can resolve dependencies and apply updates.

Finding an older version in an index is useful for investigation. It does not mean that version is the best choice for a new server, or that it is the version your configured repositories will currently install.

Search by a file you recognize

Sometimes you know the executable path but not the package name. Switch to the Files search scope instead of guessing.

Try finding packages that contain /usr/bin/htop.

That search returns packages whose indexed file metadata matches the path. You can then inspect the result for your distribution and architecture.

Using the full path helps narrow the question. Searching for just htop in file metadata can also match completion scripts or other filenames containing that text. Neither result tells you what is installed on your own machine; pkgdex searches repository metadata.

The search tabs also expose Summary, Provides, and Requires scopes. Those are useful when your starting point is a description or a dependency capability rather than a package name.

Limit discovery to one publisher

If you already know which publisher you want, a global search adds unnecessary results.

The GetPageSpeed publisher page groups our indexed repositories. For a specific example, open the GetPageSpeed search for nginx-module-brotli.

This keeps the search within GetPageSpeed while showing builds across distribution releases, architectures, and repository variants. It is a convenient starting point for checking whether we package a module for a particular target.

Before installing an NGINX dynamic module, check that its build matches your NGINX packaging and version. A search match alone does not establish compatibility. Access and subscription terms belong to the source repository; being searchable in pkgdex does not change them.

Get the results as JSON

For a script or a non-commercial project, the public API offers the same kind of package discovery without scraping HTML:

curl --fail --silent --show-error --max-time 20 \
  'https://pkgdex.org/api/search/nginx'

The response is a JSON array. Returned fields include name, version, arch, repo_name, distro, and repo_version, plus an id for looking up package details. Do not assume a single response is a complete inventory of every match.

The API documentation describes scoped searches, package detail lookup, and MCP tools for assistants. It currently specifies free use for non-commercial projects, no authentication, and a maximum of 10 requests per second.

Try your next package lookup

Start with a package name, a missing file, or a publisher you already use. Narrow the result to your distribution release and architecture, inspect the package metadata, and then return to your package manager for installation.

Try it at pkgdex.org.

How We Made NGINX Vary Cache Purges 1000x Faster

Danila Vershinin — Sun, 18 Oct 2026 06:47:30 +0000

If you purge NGINX cache entries selectively, there is a trap hiding behind one innocent response header: Vary. The moment your upstream says Vary: Accept-Encoding (or you enable gzip_vary), NGINX stores one cache file per distinct request header value under the same cache key. An NGINX Vary cache purge therefore has to remove all of those files, not just one.

ngx_cache_purge 2.6.2 fixed the correctness side of this. An exact purge now deletes every stored variant of the key, not just the variant matching the purge request's own headers. Release 2.7.0, out now, fixes the cost side. Here is the story, with benchmarks.

A purge, end to end

A minimal setup with the module loaded. The cached location itself accepts PURGE requests from localhost:

proxy_cache_path /var/cache/nginx/site keys_zone=site:10m;

server {
    listen 80;

    location / {
        proxy_pass        http://backend;
        proxy_cache       site;
        proxy_cache_key   $uri$is_args$args;
        proxy_cache_valid 200 10m;

        # same-location purging: PURGE method on the same URL
        proxy_cache_purge PURGE from 127.0.0.1;
    }
}

Now two different clients request the same URL. The backend answers with Vary: Accept-Encoding, so NGINX stores two cache files for the one key /style.css:

curl -H 'Accept-Encoding: gzip' http://example.com/style.css   # variant 1
curl http://example.com/style.css                              # variant 2

A purge is the same URL with the PURGE method. One request removes the key and every variant, and the Cache-Purge-Result header tells you exactly how many files went away:

curl -X PURGE -i http://127.0.0.1/style.css

HTTP/1.1 200 OK
Content-Type: text/html
Cache-Purge-Result: exact; count=2

<html>...<h1>Successful purge</h1><p>Key : /style.css</p>...</html>

count=2 is both variants. Before 2.6.2 the same request would have removed at most one file - whichever variant matched the purge request's own Accept-Encoding - and typically answered 412 Precondition Failed while stale variants stayed servable.

Why Vary variants are invisible to a purge

NGINX names a variant's cache file by hashing the cache key together with the requesting client's header values. The gzip client above produces one file name; the no-encoding client produces another. The purge request knows the cache key. It cannot know every Accept-Encoding string your clients have ever sent, so it cannot compute the variant file names. NGINX keeps no on-disk index of variants either. (Our proxy cache and microcaching guide covers how these cache files are laid out.)

That leaves exactly one correct way to find the variants: walk the whole cache zone and check each file's embedded KEY: line. This is what 2.6.2 does. It is the same cost class as a wildcard purge: O(every file in the zone) for a single exact purge.

How much does the scan cost?

We measured an NGINX Vary cache purge against zones of 10k, 100k and 1M small cache files. Setup: single worker, Linux ext4 in a container on Apple M2; the benchmark script (bench/variant_scan_bench.sh) ships in the module source, so the numbers are reproducible. "Warm" means the page cache already holds the zone; "cold" is the first purge after the page cache was dropped:

Files in zone	Cold purge	Warm purge	Non-Vary purge (control)
10,000	0.5 s	0.03 s	0.2 ms
100,000	4.5 s	0.2 s	0.2 ms
1,000,000	227 s	~1 s	0.1 ms

Each warm cell is the median of three trials that agreed within a few percent. The non-Vary control purge stayed at a fraction of a millisecond across every zone size and run. That control is the measurement noise floor, and the effects above sit two to six orders of magnitude over it. These are order-of-magnitude numbers from a laptop-hosted VM, not lab-grade latencies, but the shape is unambiguous.

The scary part is not the number itself. It is that the NGINX worker is blocked for the whole scan. A purge that takes 4.5 seconds means one worker serving nothing for 4.5 seconds. On a CDN-sized zone with a million files, a cold purge parks a worker for minutes.

The fix: a variant index that never guesses

Version 2.7.0 introduces a shared-memory variant index: a map from each cache key to the variant hashes that were stored or served for it. When an exact purge finds the key in the index, it unlinks exactly those files. That is O(number of variants) instead of O(zone).

The interesting part is how it stays correct. An index that might be missing a variant is worse than no index. Trusting it would leave stale content servable after a "successful" purge, which is precisely the bug 2.6.2 eliminated. So the index follows one rule:

An index entry is created only at the moment an exact purge has just removed every file for the key. That is the one state in which "no variants exist" is provably true.

From then on, a header filter records each variant NGINX stores or serves into that entry. Anything that casts doubt drops the entry: an NGINX restart, the entry being evicted under index memory pressure, or more than 64 variants on one key. The next purge then simply falls back to the full scan, which re-seeds the index on completion. Stale entries pointing at files the cache manager already evicted are skipped harmlessly. Correctness is never traded for speed; the worst case is always exactly the 2.6.2 behavior.

In practice that means: the first exact purge of a Vary'd key in an NGINX instance's lifetime scans. Every purge after that is indexed.

Which purges pay what

Not every purge is affected, and the expensive case is narrower than it may sound:

Purge request	Cached response	What happens	Typical latency
`PURGE /style.css`	no `Vary` header	direct key lookup, one file unlinked	sub-millisecond, any zone size
`PURGE /style.css`	has `Vary`, first purge of this key	full zone scan, index seeded	seconds to minutes, grows with zone size
`PURGE /style.css`	has `Vary`, repeat purge	index lookup, variants unlinked directly	milliseconds, any zone size
`PURGE /css/*` (wildcard), `purge_all`, cache tags	any	zone walk by design - candidates cannot be enumerated	grows with zone size

Two practical notes. You can tell which path a purge took from the error log at info level: the scan logs exact purge removed N vary variant(s) and the indexed path appends via variant index. And if a response should never have had variants in the first place, proxy_ignore_headers Vary in the cached location avoids the whole topic - at the price of serving one representation to all clients.

The payoff

Same benchmark, index enabled (the default):

Files in zone	First purge (scan, seeds index)	Repeat purge (indexed)
100,000	17.7 s (cold)	0.2-0.4 ms
1,000,000	-	1-5 ms

Repeat purges land in the 0.2-2 ms range regardless of zone size. At a million files that is roughly a 1000× improvement over the warm scan, and five orders of magnitude over the cold one. Purge results are identical either way: Cache-Purge-Result: exact; count=N reports the same counts.

Configuration

Nothing to do. The index is on by default with an 8 MB shared memory zone, which tracks tens of thousands of purged keys. One http-level directive controls it:

# default; size it up for very large purge-heavy deployments
cache_purge_variant_index 8m;

# or always use the full scan
cache_purge_variant_index off;

Non-Vary purges never scan and never touch the index. If your upstreams send no Vary header, none of this affects you: purges were and remain sub-millisecond.

Getting it

ngx_cache_purge 2.7.0 is available from the GetPageSpeed repositories for all supported RPM and DEB platforms:

# RHEL-likes
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-cache-purge

# Debian/Ubuntu: see the repo setup instructions, then
apt install nginx-module-cache-purge

Then load the module and reload NGINX:

load_module modules/ngx_http_cache_purge_module.so;

The full changelog, directive reference and the correctness model live on the cache-purge module page.

If you run WordPress behind NGINX, the module pairs well with our WordPress cache purge setup. And if you came here comparing purging options, ngx_cache_purge vs Varnish covers the feature gap this module keeps closing.

Gixy v0.2.55: release notes

Danila Vershinin — Sat, 03 Oct 2026 17:25:48 +0000

Gixy v0.2.55 is available. Gixy analyzes NGINX configurations for security issues.

Release notes

Fixed

Crash on directives nginx itself would reject: A directive with an argument count nginx refuses to load - such as the bare proxy_pass; that NixOS's nixosTests.nginx deliberately generates through writeNginxConfig - crashed gixy with IndexError in the ssrf/proxy_pass_normalized plugins (typed directives like add_header; failed earlier, at parse time). The parser now validates argument counts against nginx's own arity rules (via the bundled crossplane analyzer) and skips such directives with a warning: nginx would never load that config, so the directive cannot influence runtime behavior. This unblocks the nixpkgs gixy 0.2.x upgrade reverted in NixOS/nixpkgs#568041.

Release and downloads | Source repository

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.