DEV Community: GetPageSpeed

Eleven PHP versions, two package shapes, one CentOS 7: shipping the PHP2Shell fix everywhere

Danila Vershinin — Fri, 23 Oct 2026 20:02:13 +0000

The day after PHP2Shell (CVE-2026-109618 and CVE-2026-109619) went public, we shipped patched PHP 5.6, 7.0, 7.3 and 8.0 for CentOS 7. I wrote up how those first backports were ported and proven. This is the follow-up: getting from "the versions we had time for" to every PHP a CentOS 7 box can run, 5.6 through 8.4, in both of Remi's package shapes.

The real problem was the matrix, not the patch

Once the fix was ported to 5.6 and 7.0, the hard engineering was done. What was left was combinatorics:

11 PHP versions (5.6, 7.0 to 7.4, 8.0 to 8.4)
2 package shapes per version: Remi's base-name php-* (replaces system PHP, from remi-phpNN) and the phpNN-php-* software collection (side by side, from remi-safe)
a different starting point per version: a frozen EL7 build, a maintained EL8+ source, or plain upstream

Doing that as 11 separate packaging repos meant 11 copies of the same build glue drifting apart. So the per-version repos were folded into one matrix repo: a matrix.yml declares each version's source, collection name, channel and twin mode, and an assemble.sh renders each CI unit's build directory from it. The SCL twin of a version is generated from the base spec, not committed by hand. Adding 7.1 and 7.2 became a matrix.yml row plus that version's patches.

Two versions (5.6 and 8.0) keep two committed specs, because Remi's base and SCL specs for them differ by hundreds of hunks (the base builds ZTS, the collection does not). Merging them would either drop ZTS from the base shape or produce an unmaintainable spec. Two small deltas over Remi beat one big one.

Where the packages live

The channel layout ended up mirroring Remi's own, which keeps the install story uniform:

Base-name php-* for version NN lives in an opt-in getpagespeed-extras-phpNN channel, enabled per transaction: yum --enablerepo=getpagespeed-extras-php74 upgrade 'php-*'. It has to be opt-in, because a base-name php from another version would out-version whatever the host runs on an unscoped yum update.
Collections (php56-php-* to php84-php-*) live in the always-enabled main repository, like remi-safe. Their names are version-prefixed, so they can never collide with anything.

PHP 8.4 was the odd one out: Remi never built it for EL7, so there was no collection to be compatible with. It became the first collection under a GetPageSpeed prefix, /opt/getpagespeed/php84 instead of /opt/remi/php84. That is why every example uses scl enable php84 -- php -v instead of a hardcoded path: scl resolves the prefix, so the commands look the same for every version.

Runtime libraries: no Remi repository required

The Remi EL7 builds link libraries only Remi ever shipped (gd3php, oniguruma5php, libicu69/73, the phpNN-runtime metapackages). Leaving those on Remi's frozen mirror would make every fresh install depend on it. They are rebuilt from Remi's own SRPMs with identical names, SONAMEs and file lists, one release higher, so a Remi host upgrades in place and a fresh host needs only the GetPageSpeed release package.

PHP 8.4 goes further and links maintained libraries instead: OpenSSL 3.5 LTS (namespaced, never replacing the system 1.0.2), ICU 74, libzip 1.11, libpq 17 and libxml2 2.13.

Testing that it serves pages, not just that it builds

Package-level tests (phpt suite, php -m parity, the PHP2Shell probes before and after, yum downgrade back to Remi) all run on the CLI. None of them prove a channel can actually serve a request through Apache.

So there is a separate runtime suite. For every channel it starts a clean CentOS 7 container and runs four scenarios:

fresh: install from the repository on an empty host
upgrade: start from a Remi host with PECL extensions and ionCube loaded, run the documented upgrade command, fail if any extension is lost
scl-fresh and scl-upgrade: the same for the collection

Each scenario serves a probe page through mod_php and through PHP-FPM behind proxy_fcgi, and asserts the SAPI, the version, the build provider, sessions, gd, intl, mbstring and opcache, that the CLI and web SAPIs load the same extensions, and that the logs are clean. It runs on every change and nightly against the published repository, and a red job there is treated as a customer-visible break. On October 24 it ran 45 of 45 green.

The result

yum -y install https://extras.getpagespeed.com/release-latest.rpm
# base-name, replaces system PHP:
yum --enablerepo=getpagespeed-extras-php74 upgrade 'php-*'
# or the collection, side by side:
yum upgrade 'php74-php*'

The same two commands work for every version from 5.6 to 8.3, and for 8.4 once its stack or collection is installed. Version-by-version details, the full fix lists and the rollback notes are in the CentOS 7 PHP2Shell guide. If you are on Ubuntu 20.04 instead, the same problem and a free fix are covered in PHP2Shell on Ubuntu 20.04.

The packages are free to install. If your CentOS 7 servers run a business, GetPageSpeed Ultra is what funds the next round of these backports.

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

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

Update, October 24: the fix now covers every PHP from 5.6 to 8.4 on CentOS 7, in both Remi package shapes. How we got there: Eleven PHP versions, two package shapes, one CentOS 7.

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.

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.