nginx-autocert-module deletes that entire apparatus. It’s an open-source dynamic module — one we wrote ourselves — that builds a complete ACME client into NGINX itself. You write one directive, autocert on;, and the server obtains, serves, and renews its own Let’s Encrypt certificates. No certbot. No cron. No reload. This is the complete guide to what it is, how it pulls that off, every directive it understands, and why a handful of its design choices are genuinely interesting rather than merely convenient.

It’s a long read, because this is the page we want to be the reference for the module. Grab a coffee. We’ll start from absolute zero and end somewhere only the people who hold the private keys usually get to stand.

What is ACME, and what is nginx-autocert-module?

Quick refresher, because we promised to start from nothing. ACME — Automatic Certificate Management Environment — is the protocol Let’s Encrypt uses to hand out TLS certificates. Instead of filling in a form and paying a certificate authority, your server proves it controls a domain by answering a challenge, and the CA signs a certificate in return. That’s the whole idea: control the domain, get the cert.

Certbot is just one program that speaks ACME. It’s not the protocol — it’s a client. A perfectly good one, but a separate, standalone thing that lives next to your web server and has to be told, repeatedly, what your web server is doing.

nginx-autocert-module is a different ACME client — one that happens to live inside your web server. It ships as two small .so files you load with load_module. Once loaded, it reads the server_names you already declared in your vhosts, asks Let’s Encrypt for a certificate for each, serves them, and renews them on a schedule it runs internally. You don’t maintain a list of domains anywhere. Your existing config is the list. Add a vhost, get a certificate. Delete it, stop renewing. The config is the single source of truth, the way it always should have been.

If you’ve read our guide to the Angie web server, you’ll know Angie — and commercial NGINX Plus — already ship a native acme directive. Open-source mainline NGINX has nothing of the sort. This module fills exactly that gap: it gives plain, free, upstream NGINX the one feature people most often reach for a paid fork or a sidecar tool to get.

The one line that does everything

Here’s a complete, working TLS server. Read it twice, because the thing that’s missing is the entire point:

http {
    resolver 1.1.1.1;                 # the ACME engine needs DNS to reach the CA
    autocert on admin@example.com;    # global ACME contact

    server {
        listen 443 ssl;
        server_name example.com www.example.com;
        autocert on;                  # both names get a certificate
    }
}

Notice there is no ssl_certificate line. None. And here’s the thing every NGINX admin’s brain just flagged: normally NGINX flatly refuses to start a listen ssl; server without one. It’s a hard, boot-stopping error. So how does this even come up?

The module seeds the server with a throwaway self-signed bootstrap certificate the instant NGINX starts. The listener comes up immediately, handshakes succeed (your browser will grumble about the self-signed cert for a few seconds, that’s expected), and the very first time a real certificate lands on disk it gets swapped in transparently. Your server is never down waiting for issuance. And if you do already have an ssl_certificate line — say you’re migrating from certbot — the module keeps it as the pre-issuance fallback and overrides it per-connection once the real Let’s Encrypt cert arrives. Zero-downtime by construction.

Why put the ACME client inside the server at all?

Reasonable question. Certbot works. Millions of servers run it. Why reinvent the wheel and stuff it inside NGINX?

Three reasons, and they compound.

One: the config is already the source of truth. An external client has to be told your domains — a CLI flag, a config file, an Ansible template, something that has to be kept in sync with your actual vhosts by hand. Every “I forgot to add the cert for the new subdomain” outage traces back to that gap. When the client lives in the server, the gap can’t exist. The names it provisions are literally the names the server is configured to answer for.

Two: no reload on renewal. We’ll dedicate a whole section to this below, because it’s the headline trick — but the short version is that an in-server client can swap a renewed certificate into a live listener without an nginx -s reload. An external client fundamentally cannot; it can only rewrite a file and ask NGINX to re-read it.

Three: the ACME client lives inside NGINX, not bolted on beside it. Certbot runs as root (or close to it), writes keys to disk, and trusts a deploy hook to do the reload. The module instead runs the whole ACME engine — network chatter with the CA, the renewal clock, the key handling — on a single NGINX worker, the same way Angie‘s built-in acme and the official Rust nginx-acme do. No separate daemon, no cron, no deploy hook. More on exactly how next.

How it actually works under the hood

This is where the module gets opinionated in a good way. All the ACME machinery — talking to Let’s Encrypt, the renewal clock, building CSRs — runs on one NGINX worker (worker 0), driven by a timer on NGINX’s own event loop. Exactly one worker ever runs it: an flock on a lock file in the certificate store hands the role cleanly from one process to the next across a reload or upgrade, so two copies never race the CA or fight over the account. This mirrors how Angie’s native acme and the official Rust nginx-acme work — and it’s a deliberate change from an earlier design that used a separate privileged helper process (which turned out to be the odd one out and the source of a nasty cold-start edge case).

The keys live in one place: the account key and every certificate’s private key are generated and held by that single ACME worker, and on disk they sit in a store directory owned by the worker user, mode 0700, with each private key at 0600. NGINX reads a certificate back at handshake time; nothing outside that worker user can read the key material. It’s the same model the rest of the in-server ACME ecosystem (Angie, nginx-acme) settled on — run the client where NGINX already runs, keep the store locked down to the service user, and don’t spread key material across every process on the box.

And it isn’t a hacked-up background thread or a forked shell script. The engine is just a timer on a normal NGINX worker’s event loop, so it answers the same QUIT / TERMINATE / REOPEN signals as every other worker, survives reloads, and if that worker ever crashes the master respawns it and the ACME role re-arms automatically on the new one. It behaves like a first-class part of NGINX because, structurally, it is one. (Getting the single-runner hand-off right across reloads — so exactly one worker drives ACME at any instant, with no gap and no overlap — was the fiddly part; the gory details are in the project’s commit history if you enjoy that sort of pain.)

When a name needs a certificate, the engine walks the full RFC 8555 dance, end to end:

1. Register (or reuse) an ACME account, keyed by an ECDSA account key.
2. Open an order listing the domains it wants certified.
3. Fetch the authorization for each domain and answer its domain-control challenge.
4. Poll the CA until validation flips to valid.
5. Send a certificate signing request (CSR) built fresh for that domain.
6. Poll the order until it’s valid, then download the signed chain.

It writes the result atomically into a per-domain directory: private key at 0600, full chain at 0644, all under a 0700 store owned by the worker user. Workers read only the certificate and chain, only at handshake time, never the account key. Atomic write means a renewal half-finishing — power loss mid-download — never leaves a worker reading a truncated certificate; it sees the old complete one until the new complete one is fully in place.

The headline trick: no reload on renewal

Here’s the feature that makes this more than a certbot reskin, and the reason an in-server client is worth the trouble.

With the traditional stack, renewing a certificate means rewriting a file and then telling NGINX to reload so it re-reads that file. At one or two domains, who cares. At a few hundred, that reload becomes a recurring, slightly racy event you’d really rather not fire off a timer: every reload spins up a fresh set of workers, drains the old ones, and for a beat your connection-handling capacity wobbles. Do it for a cert renewal and you’re paying a whole-server hiccup to update one file.

nginx-autocert-module doesn’t reload at all. Certificates are loaded per-SNI, at the TLS handshake, straight from disk — and a worker only re-reads a certificate file when its modification time changes. So when the helper renews a certificate, it just writes the new file. The next client to connect for that hostname triggers a fresh read; everyone already connected keeps using the cached one. The renewal takes effect on the next handshake, with zero reloads, zero dropped connections, and zero capacity wobble.

The clock that drives all this runs on that same ACME worker. It sweeps periodically, checks each certificate’s expiry, marks one “due” once it enters the autocert_renew_before window — 7 days by default — and reissues it. One order at a time, so a server with hundreds of domains doesn’t open hundreds of simultaneous ACME orders and trip a rate limit. Quiet, paced, and invisible until the day you notice you haven’t thought about certificate expiry in months.

Two ways to prove you own the domain

ACME needs you to demonstrate control of each domain before it’ll sign anything. The module supports two challenge types, and you pick with a single directive.

HTTP-01 — the default

HTTP-01 serves a magic token at /.well-known/acme-challenge/<token> on port 80. The CA fetches that URL; if it gets the right token back, you’ve proven control. The module answers it with a built-in handler — no location block, no webroot directory, no separate listener to babysit. The token lives in shared memory and vanishes the instant validation passes. It’s the path of least resistance and it works for the overwhelming majority of setups.

TLS-ALPN-01 — for the port-80 refuseniks

TLS-ALPN-01 (RFC 8737), set with autocert_challenge tls-alpn-01;, is the cooler one. It validates entirely inside the TLS handshake. When Let’s Encrypt connects negotiating the special acme-tls/1 ALPN protocol, the module presents a one-off certificate carrying a magic extension, and that is the proof — no HTTP request, no port 80 involved at all.

The payoff: you never have to open port 80. For anyone running a locked-down, HTTPS-only edge — where 80 is firewalled shut on principle — that’s a genuine win, not a party trick. It was also surprisingly fiddly to implement correctly, because NGINX doesn’t give you a polite way to chain its ALPN selection callback; you have to thread your handshake-time certificate in without breaking the normal path. Worth it, though.

ECDSA only — and the CA is treated as the enemy

Two security decisions worth calling out, because they’re the kind of thing that separates “a tool that works” from “a tool you’d trust with your private keys.”

First: there is no RSA anywhere. Account keys and certificate keys are ECDSA P-384 by default (P-256 if you ask via autocert_key_type secp256r1;). Smaller keys, faster signatures, less work on the handshake hot path — and it’s squarely where the CAs and the wider ecosystem are heading. If you care about modern crypto on your edge, you’ll also enjoy our write-ups on getting an A+ on SSL Labs and post-quantum TLS on NGINX and Angie.

Second — and this is the part security folks will appreciate — the module treats everything the CA says as hostile network input. That sounds paranoid until you remember the CA’s responses arrive over the network, and anything that arrives over the network can be tampered with, malformed, or hostile if the connection is ever compromised. So the module ships its own depth-bounded JSON parser and a strict base64url decoder that rejects garbage rather than silently truncating it — which is exactly what NGINX’s permissive built-in decoder would happily do, and exactly the kind of silent-truncation behaviour that turns into a security bug three years later. Every single ACME request verifies the CA’s certificate chain and hostname; there is no “skip verification” escape hatch, not even a hidden one for testing. A full security proofread of roughly ten thousand lines of C turned up zero memory-safety, parser, or TLS-verification bugs. For a thing that parses attacker-reachable input and holds your private keys, that paranoia is precisely the right amount.

The directive reference

Everything you can configure, in one place. Most people will only ever touch the first one.

The canonical, always-current reference lives in the project’s README — see the link at the end — but the table above covers everything in normal use.

How it compares: certbot, Angie, and this module

Not a fight — a “pick the right tool” table. All three speak ACME; they differ in where the client lives and what that buys you.

The honest summary: if you’re on Angie, use Angie’s built-in acme — it’s excellent and this module runs and is tested on Angie too, but Angie’s own is the natural choice there. If you need wildcards or DNS-01 today, certbot is still your friend. If you’re on mainline NGINX and you want the in-server, no-reload experience without switching forks, this module is the one that didn’t exist until we wrote it.

What it doesn’t do (yet)

Honesty section, because cornerstone pages that only list strengths age badly. Today the module does full issuance and renewal on mainline NGINX, both challenge types, ECDSA keys, and robust rate-limit handling — it even honours Let’s Encrypt’s Retry-After header and backs off per-domain so it never hammers the CA. What it doesn’t do yet:

• Wildcards and DNS-01. Not supported. The “use the names already in your config” model doesn’t cover *.example.com, which fundamentally needs DNS-based validation — a different challenge type that proves control of the whole zone, not one hostname.
• Multiple CAs / EAB. One CA, one account at a time. No External Account Binding for commercial ACME CAs yet.
• Angie. The module builds and runs on Angie, and the full end-to-end test suite runs against Angie on every change — but since Angie ships its own native acme, that’s the natural choice there. The module coexists with it if you want it.

It builds as a clean dynamic module against current mainline NGINX, and it’s part of the same family as our other modules over on the NGINX modules repository.

Frequently asked questions

Do I still need certbot or a cron job?

No. nginx-autocert-module is the ACME client, and it runs its own renewal timer inside NGINX. There’s nothing external to install or schedule — no certbot package, no cron line, no systemd timer.

Does NGINX reload when a certificate renews?

No. Renewed certificates are written to disk atomically and picked up at the next TLS handshake via a modification-time check. No nginx -s reload, no dropped connections, no capacity wobble.

Which certificates does it request — do I list domains somewhere?

There’s no separate list. It provisions the concrete server_names already declared in any vhost that has autocert on;. Regex and wildcard server names are skipped, because they don’t name a concrete host to certify.

Can I get certificates without opening port 80?

Yes — set autocert_challenge tls-alpn-01;. Validation then happens entirely inside the TLS handshake (RFC 8737), so port 80 can stay firewalled shut. Otherwise HTTP-01 serves the challenge on port 80.

Can I get RSA certificates?

No. Keys are ECDSA P-384 by default, or P-256 if you set autocert_key_type secp256r1;. Note those are the OpenSSL curve names, not p384/p256. RSA is intentionally not an option.

Where are the private keys, and who can read them?

One NGINX worker (worker 0) runs the ACME engine and generates the account key and every certificate key. On disk they live under <autocert_path>/ at 0600, inside a 0700 store owned by the worker user — so make sure that directory is writable by the user NGINX drops to (the user directive). If you’re upgrading from an older build whose store was created by root, chown it to the worker user once before restarting.

Will NGINX start if I haven’t gotten a certificate yet?

Yes. A listen ssl; autocert on; server with no ssl_certificate starts immediately behind a self-signed bootstrap certificate, then swaps in the real one per-SNI the moment issuance completes.

What happens if Let’s Encrypt rate-limits me?

The scheduler backs off per-domain — exponential, from 60 seconds up to an hour — and honours a CA Retry-After header on HTTP 429, waiting the later of the two deadlines before retrying. It won’t get your account throttled.

Does it work with HTTP/3 and the rest of a modern NGINX stack?

Yes. It’s a standard dynamic module and doesn’t care what else you’ve loaded. Pair it with our HTTP/3 and QUIC setup guide and the certificates it issues are served over whichever protocols your listeners speak.

Where to get it

The module is open source and lives on GitHub: github.com/eilandert/nginx-autocert-module. The README there has the full directive reference, build instructions, and the CI matrix we run on every change. If you run our packaged NGINX builds, keep an eye on the modules repository page — that’s where it’ll show up as a drop-in package you can apt install instead of compiling.

Related reading

• Angie Web Server: The Complete Guide — review, native ACME, migration, API and HTTP/3.
• TLS Configuration for NGINX and Angie — the complete guide to an A+ on SSL Labs.
• Post-Quantum Cryptography with NGINX and Angie — ML-KEM and hybrid TLS.
• HTTP/3 and QUIC on NGINX — real-world setup, tuning and gotchas.
• NGINX APT Repository for Debian & Ubuntu — 100+ modules, no compiling.

If you run a mail server, you know the feeling. A user forwards you a “weird invoice”, you open it in a sandbox six hours too late, and there it is: an auto-exec macro that would have phoned home the moment someone clicked Enable Content. The fix is not hope. The fix is to crack every Office attachment open at the gateway and read its macros before your users ever see them. Rspamd can do exactly that, with a little help from a tool called olefy and the Python library underneath it.

This post walks the whole pipeline: what olefy is, how rspamd talks to it, where the stock setup quietly falls apart under load, and the wrapper we built — olefied — to make it survive a real mail stream. Want the wider spam-filtering picture first? Our rspamd explainer covers Bayes, neural nets, RBLs and the rest. This one zooms all the way in on a single module.

Why Office macros still get people killed (figuratively)

A VBA macro is just code. Word and Excel will happily run it, and for thirty years that has been a feature, not a bug. Finance teams automate spreadsheets with it; attackers automate your ruin with it.

The classic attack chain is depressingly short. Spam lands. The victim opens the attachment. The document looks blank or “broken”, so the victim clicks the yellow Enable Content bar to fix it. The macro fires, pulls a second-stage payload off some compromised WordPress site, and now you are hosting someone else’s botnet.

The macro itself almost never carries the real weapon — it carries a downloader, usually obfuscated to hell so a plain string search finds nothing. Think Base64 inside a string-reverse inside a split-and-concatenate, eventually calling WScript.Shell or spawning PowerShell with -enc. You cannot catch that by grepping the file for “powershell”. You have to actually parse the OLE structure, pull the macro streams out, and look at what the code does.

That parsing is exactly what oletools does. It is a Python toolkit by Philippe Lagadec that has been the reference for Office-document forensics for over a decade. The piece we care about is olevba: hand it a file and it digs out every macro, decodes the obvious obfuscation, and flags the suspicious calls — auto-exec triggers, shell-outs, suspicious URLs, the works. It speaks fluent malware-analyst. The catch: it is a command-line Python program, and your mail filter is a long-running C daemon scanning thousands of messages a minute. It is not about to fork a Python interpreter for every attachment.

How rspamd hands a file to olevba

Rspamd does not call olevba directly — spinning up Python per message would melt your box by lunchtime. Instead it has an external-services mechanism (the oletools module, part of the external_services family) that talks to a small network service over a TCP socket. You point rspamd at a host and port, it streams the attachment bytes across, and it gets back a verdict it can turn into a symbol and a score.

That little network service is olefy. Carsten Rosenberg and Dennis Kalbhen at Heinlein Support wrote it precisely to bridge the gap: a long-lived socket daemon that pays the expensive Python startup once and then runs olevba on demand. Rspamd connects, sends a tiny header plus the raw document, and olefy shells out to olevba, scrapes its JSON, and ships it back.

The wire protocol is deliberately dumb, which is a compliment. A request looks like this:

OLEFY/1.0
Method: oletools
Rspamd-ID: a1b2c3

<raw bytes of the .docm here>

Header lines, a blank line, then the file. The client half-closes the connection to say “that’s all the bytes”, olefy runs the scan, writes back a JSON array, and closes. There is also a health check: send PING\n\n and a healthy olefy answers PONG. That is the entire contract — you can test it with nc and a sacrificial document, which is the kind of debuggability you learn to treasure after your third opaque enterprise appliance.

Wiring it into rspamd is four lines:

# external_services.conf  (or oletools.conf)
oletools {
  servers  = "olefy:10050";
  timeout  = 15s;
  max_size = 5M;
}

Set the server, give it a timeout so a slow scan cannot wedge the whole message, cap the size so nobody feeds you a 2 GB “spreadsheet”, reload rspamd, done. Macros in attachments now get parsed and scored. For about a week, you feel clever.

Where stock olefy quietly falls over

Here is the part nobody puts in the README. Olefy is a single-threaded asyncio server, and when a request comes in it runs olevba as a blocking subprocess on the event loop. Read that again. While one document is being scanned, the entire daemon is frozen and every other connection waits. On a quiet personal server you will never notice. On a mail relay during a Monday-morning malware blast, you have just turned your parallel filter into a single-file queue — and olevba on a nasty document can take a second or three.

It gets worse. There is no scan timeout. None. olevba is a big pile of parsing code chewing on hostile input, and hostile input is the entire point of the exercise. Feed it a malformed or maliciously crafted document and it can hang — and stock olefy will wait for that subprocess forever. The upstream answer is a systemd unit that restarts the service every four hours, which is the software equivalent of rebooting the router when the wifi gets weird. It works, in the sense that a brick works as a paperweight.

And the input buffer is unbounded. A client that opens a connection and dribbles bytes without ever closing will grow that buffer until the kernel gets unhappy, the OOM killer wakes up, looks around, and shoots your scanner in the head. Then your external_services calls start timing out, rspamd logs a wall of errors, and you are reading this at 3 a.m. wondering why “the spam filter” is down — when the spam filter is fine, and the macro scanner is the corpse.

None of this is a knock on olefy. It does one job, the code is clean, and it was written for a workload of “one mail server, reasonable volume” — for which it is perfect. The trouble starts when you put it in front of real throughput and expect it to behave like a service instead of a script. So we wrapped it.

olefied: the same olefy, built to take a beating

We kept Heinlein’s olefy.py exactly as it is — not a line changed. olefied is a thin front-end that sits in front of one or more unmodified olefy processes and fixes the operational problems without touching the thing that already works. The whole front-end is one file, olefyd.py, and the design is the boring-on-purpose kind that survives contact with production.

Concurrency. olevba is CPU-bound, so the right model is a pool, not a thread pile. olefied launches a set of olefy worker processes (one per CPU by default), each on loopback with its own private scratch directory, and load-balances scans across them from an idle queue. One in-flight scan per worker: a request grabs a free worker, runs, hands it back. When every worker is busy, the next request waits a short, bounded time and then gets a clean “busy” answer instead of piling onto an ever-growing backlog. That is backpressure — the difference between a service that degrades and one that face-plants.

The scan timeout, the big one. Every scan is wrapped in a hard deadline. Blow the deadline and olefied assumes that worker is wedged on a poison document, kills it, and spawns a fresh one. The bad message gets an error verdict, the worker is back in under a second, and the other workers never even noticed. No four-hour restart cron. No frozen daemon. The thing that pages you at 3 a.m. simply stops being a thing.

Limits and self-healing. Uploads are capped, so the dribble-forever trick hits a wall instead of your RAM. Connections are capped too, which bounds how much memory all those in-flight uploads can hold at once. And a small supervisor loop watches the pool: any worker that has died — or come back but gone mute — gets recycled. The pool heals itself while you sleep, which is the only time pools ever break.

Through all of this the wire protocol is untouched. PING still returns PONG; an OLEFY/1.0 request still gets the same JSON back. Your existing rspamd config does not change one character — you point it at olefied instead of olefy, and nothing downstream can tell the difference, except that it stops falling over.

The cheapest scan is the one you don’t run

Here is the trick that buys the most headroom, and it is almost embarrassing: the same attachments show up over and over. A malware campaign sends the identical .xlsm to ten thousand mailboxes. A mailing list staples the same footer document to every digest. People forward the same quarterly report around the company until the heat death of the universe. Scanning that file a thousand times to get the same answer a thousand times is CPU you are paying for and throwing away.

So olefied has an optional result cache, backed by redis. Point it at a redis URL and successful scans get cached, keyed by a SHA-256 of the document body. The next time that exact document arrives, the answer comes straight out of redis and no worker is touched at all.

The key hashes the document only, not the per-message Rspamd-ID header, so the same attachment in different mails is one cache entry, not ten thousand. The oletools version is baked into the key too, so the day you upgrade oletools, the old cache transparently stops matching — you are never served stale verdicts from a parser that has since learned new tricks.

Two things matter here, and we got both right:

• Only successful scans are cached. Errors, timeouts and busy responses are never stored, because caching a transient failure is how you turn a blip into an outage that outlives its cause.
• The cache can never take the scanner down. If redis is slow or dead, the lookup is treated as a miss and the scan just runs. The cache is an accelerator, not a dependency.

On real mail you will see hit rates in the 30–70% range, and every hit is a scan you did not pay for. Run several copies of olefied behind a load balancer and they all share one redis, so a document scanned by one replica is free for all the others.

How fast is it, really

Throughput here is not a vibe, it is arithmetic. olevba is CPU-bound and a worker scans one document at a time, so per container the ceiling is roughly:

sustainable msg/s  =  workers / average_scan_seconds

A small attachment scans in something like 50–200 milliseconds, so a single worker handles maybe 5–20 documents a second. Give the container more cores and the worker count rises with them. Need more than one box can do? Run more replicas behind your TCP load balancer — they are stateless, so total throughput is just the sum, climbing in a straight line until you run out of CPU. The cache bends that line further in your favour by removing scans entirely.

Do not take my word for it, and do not take a vendor’s either — measure it on your own hardware with your own documents, because your attachment mix is not mine. olefied ships a small benchmark script: paste a representative file into sample.bin, run it with a concurrency and a request count, and it prints messages per second plus p50 and p95 latency. Warm the cache first if you want the hit-path numbers. Benchmark one replica in isolation, then multiply. The honest number you get beats the optimistic number somebody put on a slide.

Running it without making yourself a target

You are about to run a fully untrusted-input parser as a network service. Treat the container as hostile territory, because its entire job is to eat hostile files. The image runs as a non-root user, ships as a multi-stage build with no compiler or build tools in the final layer, and binds the workers to loopback only so the sole exposed thing is the dispatcher. It runs happily read-only with a tmpfs for scratch. Here is the hardened invocation:

docker run -d --name olefied --init \
  --read-only --tmpfs /tmp:rw,mode=1777,size=512m \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --memory 1g --cpus 4 \
  -e OLEFIED_WORKERS=4 \
  -p 10050:10050 \
  eilandert/rspamd-olefy

Drop all capabilities, forbid privilege escalation, set memory and CPU limits so a runaway scan cannot starve its neighbours, and in a real mail stack keep it on an internal network with no published port. If any of that container hardening is new to you, our Docker hardening guide walks through every flag and why it earns its place. The --init flag adds a PID-1 reaper as belt-and-suspenders; olefied already waits on the workers it spawns, but reaping is cheap insurance.

One detail I am quietly proud of: the image pulls olefy.py and its requirements fresh from Heinlein’s upstream at build time instead of carrying a vendored copy, so every rebuild tracks their latest. It is built daily alongside the rest of our dockerized images, so you are never more than a day behind upstream oletools and its parser fixes. Prefer to pin a known revision for a reproducible build? Pass a build argument and you get exactly that. The image is on Docker Hub; the source, the dispatcher, the tests and the benchmark live on GitHub.

Frequently asked questions

Where to go next

• Rspamd explained — the full spam-filtering picture: Bayes, neural nets, RBLs, Pyzor, Razor and where olefy fits in.
• Docker hardening for self-hosters — every flag in that hardened run command, explained.
• Our dockerized images — how the daily-rebuilt image factory works, olefied included.
• Where to find us — every repo, Docker image and GitHub project in one place.
• olefied on GitHub and on Docker Hub, built on Heinlein’s olefy.

So: the next “weird invoice” that lands in your queue gets its macros read by a machine that never clicks Enable Content, never gets tired, and never wonders if this one is fine. Go point rspamd at it — then back up your config before you touch the timeout.

If you’ve never met YARA: it’s the pattern-matching engine malware analysts use to describe and detect families of nasty files. Think of it as grep that understands “this looks like a malicious PDF dropper” instead of “this line contains the word cat.” VirusTotal runs it. Every threat-intel team writes rules in it. And it’s genuinely useful bolted onto a mail filter, because email is still how most malware introduces itself to your users. Yet rspamd, the best open-source spam filter going, has no native YARA module. Let’s talk about why, and what to do about it.

The module that doesn’t exist

Here’s how the conversation usually goes. Someone wires up rspamd, reads that it does Bayes, neural nets, RBLs, fuzzy hashing, DCC, Razor, Pyzor, the works, and assumes YARA is in the pile somewhere. It feels like it should be. YARA is the obvious tool for “scan this attachment against a pile of malware signatures.” So they go looking for local.d/yara.conf and come up empty.

I did the responsible thing and checked the running container before trusting my own memory. Grepped the whole config tree for “yara.” Nothing. Checked whether the rspamd binary was even linked against libyara. It wasn’t. Looked for the plugin Lua file that every native module ships. Not there either.

$ docker exec rspamd sh -c 'grep -rli yara /etc/rspamd/; rspamadm configdump | grep -ci yara'
0

Zero. The upstream answer is the same: YARA scanning is a feature request, discussion #3511, still open, still unimplemented as of rspamd 4.1. The closest thing rspamd will tell you is “use ClamAV, it can load YARA rules.” Which is true, and also a trap, and we’ll get to why.

None of this makes rspamd bad — it’s superb at what it does (the full tour: rspamd, Bayes, neural nets and RBLs). YARA just isn’t in the toolkit yet. So how do you add it without making a mess?

Your three options, ranked by how much they’ll hurt

When a tool you love is missing a feature, you’ve got the usual choices, and they’re rarely equal.

Option one: shove YARA into ClamAV. Clamd loads .yar files and rspamd already talks to ClamAV. On paper, done. In practice your rules become hostages of clamd’s reload cycle, you can’t score individual rule hits (everything is one generic CLAM_VIRUS verdict), and debugging which rule fired means spelunking clamd logs. A precise instrument turned blunt. It works. It’s grim.

Option two: write a pure-Lua YARA plugin. Rspamd’s plugins are Lua, so surely you just call libyara from Lua and you’re done? No. libyara is a C library with a CGO-shaped hole where its bindings should be, and rspamd’s Lua runtime has no YARA bindings at all. Even if it did, running a full YARA scan inside the rspamd worker means doing heavy CPU work on the event loop. That loop is the thing keeping your mail flowing. Block it and you don’t have a spam filter, you have a very expensive way to make Postfix queue up.

Option three: run YARA out of process, over HTTP. The worker fires an async request, a separate service scans, the answer comes back, the worker never blocks. More code up front, but the only option that doesn’t make you hate your life in six months. So that’s the one.

That pattern is familiar: rspamd already does it for the collaborative networks. DCC, Razor and Pyzor are CLI tools behind a small HTTP backend I’d built in Go, gozer — and the YARA scanner is its sibling. Same shape, different payload.

What YARA actually does, for the uninitiated

Before the plumbing, the engine. A YARA rule is a tiny declarative program: “a file matches if it contains these patterns under these conditions.” Here’s the canonical harmless one, matching the EICAR test string every antivirus recognises:

rule EICAR_Test_File : test
{
    meta:
        description = "EICAR antivirus test pattern"
    strings:
        $e = "$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!"
    condition:
        $e
}

Three parts. meta is free-form notes (author, what it catches, severity). strings declares patterns — plain text, hex, or regex. condition is the logic: match if this string appears, or three of five do, or the file starts with a PE header and holds that suspicious import. A good rule keys off structural traits the author can’t change without breaking their own payload.

That last bit matters. A signature on a literal string is trivial to evade: change the string. A rule that matches the shape of a packer stub, or the specific sequence of API calls a dropper makes, survives the malware author tweaking cosmetics. This is why threat-intel teams ship YARA rules and not just hash lists. Hashes catch yesterday’s exact file. Rules catch tomorrow’s variant.

And here’s the thing people miss: YARA is much more than a box of regexes. The engine ships file-format modules that crack a file open before you match anything. The pe module parses a Windows executable, so a rule can say “imports the function used to inject code into another process, and its last section is high-entropy” — entropy being shorthand for “looks encrypted or packed, the way malware hides.” There are siblings for elf, macho and .NET, a hash module for fingerprinting, and a math module for the entropy sums. None of that is expressible as a regex: a regex sees a flat stream of characters; these modules see a structured file and let a rule reason about its anatomy. That’s why a real scanner uses libyara, not grep. yarad compiles all of it.

For email you point these rules at two things: the whole raw message, and each attachment on its own. The per-attachment scan is where the real malware-hunting happens — that’s where the malicious PDF or macro-laden spreadsheet lives — and, as we’ll see, where you have to do some unpacking before the rules can even see the nasty bit.

The scanner: a small Go daemon called yarad

So I wrote yarad — deliberately boring, the highest compliment for mail infrastructure. It compiles a rule set at startup, listens on HTTP, and answers one question: “here are some bytes, which rules match?” The rspamd plugin POSTs a message or attachment, yarad scans and returns the matched rule names as JSON.

$ printf '%s' "$EICAR_STRING" | curl -s -H "X-YARAD-Token: secret" \
    --data-binary @- http://yarad:8079/scan
{"matches":[{"rule":"EICAR_Test_File","tags":["test"],"meta":{"description":"EICAR antivirus test pattern"}}]}

Under the hood it’s Go calling libyara through CGO (go-yara). The compiled rule set is immutable, so a reload compiles a fresh set and swaps a pointer atomically — in-flight scans finish on the old rules, new ones pick up the new, no long-held lock. A SIGHUP recompiles in place; a broken rule edit fails the reload and keeps the previous rules live, because the one thing worse than stale rules is a scanner that disarmed itself over a fat-fingered brace.

The build is the fiddly part. Go with CGO against a static libyara, on a distroless final image, is a minefield of glibc version skew — build on a newer Debian than the runtime base and you get:

/usr/local/bin/yarad: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

The build image’s glibc must be no newer than the runtime base’s — match the Debian releases. And don’t fully static-link glibc (it breaks dlopen/getaddrinfo): link libyara statically, leave glibc dynamic, ship on a minimal Debian-based distroless image. The result is a ~89 MB container with no shell, no package manager, running non-root — see my longer take on hardening Docker the rootless, read-only, distroless way.

Worth knowing where that 89 MB actually goes, because it’s mostly not code. About half of it — ~37 MB — is the compiled rule bundle (some 11,000 rules baked into one .yac). The distroless base and its system libraries (glibc, libssl, tzdata) are another ~25 MB. The yarad binary itself, Go statically linked against libyara and stripped, is barely ~8 MB. So the “scanner” is the small part; the rules are the weight, and they grow a little every day as the rebuild pulls the latest.

Rulesets: where the good rules actually live

A YARA scanner with no rules is a very fast way to do nothing. The whole value is in the rules, and writing your own from scratch for general malware is a fool’s errand when teams who do this full time publish theirs for free.

yarad bakes five public sources straight into the image at build time. I want to be loud about this part: these rules are other people’s work, given away for free, and they are the entire reason any of this catches anything. yarad just packages and runs them. So, with full credit and their licenses spelled out:

• YARA-Forge (the “core” bundle) is a clever project by YARAHQ: it ingests dozens of public rule repositories, deduplicates them, strips the broken and the dangerous, and ships a single curated bundle in quality tiers. You pull “core” and you’ve got vetted rules without wrangling forty git repos by hand. License: it’s an aggregator, so every bundled rule keeps its original author’s license; the build tooling itself is GPL-3.0.
• Neo23x0’s signature-base is Florian Roth’s long-running collection that powers a huge amount of the YARA scanning in the wild (it’s the engine behind the THOR and Loki scanners). License: Detection Rule License (DRL) 1.1 — a permissive, MIT-style licence written specifically for detection content.
• ANY.RUN’s rules round it out with actively maintained malware-family and phishing signatures from a well-known sandbox vendor. License: published as open detection rules (no separate licence file in the repo).
• Didier Stevens’ suite brings the document specialists — the vba.yara, rtf.yara and maldoc.yara rules that hunt malicious Office macros and RTF exploits, which matter enormously for mail. License: public domain (“no copyright, use at your own risk”).
• bartblaze’s Yara-rules adds maldoc, RTF and phishing-document rules that aren’t aggregated into YARA-Forge. License: MIT.

Together that’s around 10,000 compiled rules covering malware, webshells, suspicious documents and phishing kits — and the licences are all permissive (DRL, MIT, public domain). I deliberately turned down richer but restrictive sets (Elastic’s own licence, the GPL-only Yara-Rules project): baking a copyleft or “no managed service” clause into a public MIT image drags it onto everyone who pulls the image.

Compiling ten thousand rules isn’t free, so yarad doesn’t do it at startup. The rules are precompiled into a single binary bundle at image-build time, and the running container just loads that ready set instead of building one. Startup is instant, and the loaded set looks like this:

compile-rules: bundled 745 files (13 skipped) -> /rules/compiled.yac
[yarad] loaded 10385 YARA rules from /rules/compiled.yac

Those 13 skipped files are the other lesson: public rulesets are messy. Some import modules I didn’t compile in, others use THOR/Loki external variables that only make sense scanning files on disk. So each rule file is test-compiled on its own first and a single rotten one is logged and skipped, fatal only if nothing compiles. Test rule loading against the real ruleset, not a toy rule, or you meet your first broken file in production with zero rules loaded.

Baking the rules into the image (a daily rebuild re-pulls the latest) means they track a dated, rollback-able artifact, not a mutable folder nobody remembers editing — same logic as pinning a package version. One caveat: running rules you didn’t write is running internet logic against your mail. YARA can’t execute code, so the blast radius is a noisy false-positive, not a shell — but treat a rule source like any dependency: know the maintainer, pin it, watch what it flags first.

Documents are where the malware hides: OLE, RTF and macros

Here’s a problem that breaks naive scanners, and it took me a beat to appreciate how badly. You bake in ten thousand rules, including a pile that specifically hunt malicious Office macros, and then you scan a real malicious spreadsheet… and nothing fires. The rules are right there. The macro is right there. They just never meet. Why?

Because a modern Office document is a Russian doll. A .docm/.xlsm is secretly a ZIP holding a vbaProject.bin — itself an older OLE2 container (same as legacy .doc/.xls) — and inside that the macro code is stored compressed (Microsoft’s MS-OVBA). So a rule hunting telltale words like AutoOpen or Shell stares at a compressed blob: the words are there, squished into gibberish, and the rule sees nothing.

Step one: unwrap and decompress

So before yarad matches a single rule, it cracks the doll open. It sniffs the first few bytes of every attachment to recognise the two container shapes (OLE2 and ZIP), unzips the modern ones in memory, finds the embedded macro project, and decompresses the VBA back into the plain source the attacker actually wrote. Then it scans both things: the raw bytes (for rules that hunt file-format exploits) and the decompressed macro source (for rules that hunt suspicious keywords). The matches get merged together. Suddenly all those macro rules can see the macro, and they fire exactly when they should.

The nice part: this is done entirely in Go, with a pure-Go library called oleparse, so there’s no extra C dependency and no Python in the hot path. And there’s a little flourish — while scanning the decompressed source, yarad flips an internal switch (a YARA “external variable” called VBA) to true, so Didier Stevens’ macro-keyword rules fire on the cleartext macro but stay quiet on raw bytes, where the same keywords would just be noise.

RTF files — the other classic malware vehicle, home of the famous Equation Editor exploit — work differently and need no unpacking: they smuggle their payload as hexadecimal text right there in the raw file, so the RTF exploit rules match the raw bytes directly. Different shape, same outcome: the rule meets the malware.

Step two: un-disguise the URLs

Malware authors know macros get scanned, so they disguise the addresses their code phones home to: hxxp://evil[.]example/payload — “defanged” so a dumb scanner doesn’t recognise it. yarad un-disguises these on every buffer, rewriting hxxp→http, [.]/(dot)→a dot, putting the threat back in plain sight.

Why bother? Because of the next trick: yarad can check every URL it finds — in the message and in those decompressed macros — against URLhaus, abuse.ch’s free feed of known malware-distribution links. With an abuse.ch key it pulls the feed into memory periodically, so every lookup is an instant local check, never a per-message API call. A macro reaching a URL known to serve malware is about as close to a smoking gun as mail scanning gets — and one that only matched after un-disguising is flagged as more suspicious still. A dead feed just means a miss; it never holds up mail.

How this compares to Python’s oletools

If you’ve done maldoc analysis you know oletools — Philippe Lagadec’s Python suite (olevba, mraptor, oleid, rtfobj), the reference toolkit for pulling documents apart. I run it elsewhere in this stack, wrapped as olefy. So why duplicate it in yarad?

Because with the unpacking step above, yarad covers roughly 80% of what oletools does for mail — in-process, in Go, no Python, no second service. It extracts and decompresses the VBA (the heart of olevba), detects suspicious-keyword and auto-run patterns (olevba indicators, mraptor‘s heuristic), spots encrypted or macro-bearing documents (oleid‘s job), catches RTF and embedded-object exploits, and goes beyond oletools by reputation-checking the extracted URLs against URLhaus. For the overwhelming majority of malicious mail, that’s enough.

The remaining ~20% is the deep tail: olevba doesn’t just notice Base64 or string-reversal, it decodes the obfuscation chain to reveal the hidden command; it emulates Excel 4.0 “XLM” macros; yarad matches the patterns of obfuscation, it doesn’t fully unwind it — which is why olefy keeps running in parallel as a second opinion. But most maldoc detection no longer needs to leave the Go process, and that’s a big win at a thousand messages a second.

Caching, or how to keep a busy mail server alive

YARA scanning is CPU work, and a busy mail server can’t scan every byte of every message from cold. The saving grace is that mail is gloriously repetitive: bulk campaigns, one body fanned out to a 500-person list, MTA retries of the identical message. Scanning all of those independently sets CPU on fire computing the same answer over and over.

So yarad caches verdicts keyed by a SHA-256 of the bytes. Scan a message once, remember the result, and every identical message after that is a microsecond map lookup instead of a scan. The cache is an in-process LRU with a TTL, always on, bounded so it can’t eat all your RAM.

The cleverer trick is coalescing. When a 500-recipient blast lands, all 500 copies arrive with the same hash before any has finished scanning. Naively that’s 500 scans; yarad’s singleflight group makes the first scan and the other 499 block on its result. One scan, not five hundred — the difference between a blip and a load spike.

yarad_scans_total 1
yarad_matches_total 1
yarad_cache_hits_total 1
yarad_cache_coalesced_total 0

For one box the in-process cache is plenty. Run several yarad replicas and you’ll want them sharing a verdict cache: point YARAD_REDIS_URL at a Redis or Valkey instance. A dead or slow Redis fails open (yarad just scans, 200 ms budget), so a cache outage means “a bit more CPU”, not “mail stops.”

That’s the rule for every external dependency on a mail path, and yarad takes it all the way. A scan error, a timeout, a panic, a libyara hiccup, all of it gets reported as “no match” and logged, never as an error that blocks the message. Spam filtering is allowed to miss. It is never allowed to eat your mail. A scanner that drops legitimate email because it crashed is infinitely worse than one that occasionally lets a sample through.

Wiring it into rspamd without blocking real mail

The rspamd side is a Lua plugin. It grabs the message content and each attachment, fires async HTTP requests at yarad, and attaches whatever matched to the message. Each matched rule comes back with the rule name and, crucially, the source file it came from, so the history shows SUSP_Just_EICAR (sigbase-gen_suspicious_strings.yar) rather than a bare rule name you then have to go hunting for. URLhaus hits show the actual offending URL. The plugin stays fully async, so the worker is never sitting around waiting on a scan.

One small but important piece of hygiene: public rulesets ship the occasional demo or teaching rule that is useless in production. Didier Stevens’ set, for instance, includes a rule literally named http whose entire logic is “the text contains the string http” — which is to say, it matches essentially every email ever sent. So the plugin keeps a small denylist (just http by default) of rule names to ignore, and you can add to it without rebuilding anything. Knowing which file a rule came from, from the line above, is exactly what lets you spot a noisy one and silence it.

One deployment gotcha: if your rspamd uses a locked-down resolver that can’t resolve Docker service names, point the plugin at yarad by container IP, not name.

Then there’s scoring, which is where careers quietly end. Public YARA rules are written to catch malware across the entire internet, not against your specific mail, and some will false-positive on something perfectly legitimate that one of your users sends every Tuesday. The naive approach is one symbol, one weight, for any rule hit — but that treats “this is the Emotet trojan” and “this looks vaguely suspicious” as equally damning, which is nonsense. So the plugin doesn’t do that.

Instead it classifies each matched rule — from its name, source file and tags — into a tier, and each tier scores differently. A confirmed malware family hits hard; a broad heuristic barely nudges. The tiers all live in one rspamd group (called YARA) and stack, capped by the group’s max_score:

group "YARA" {
  max_score = 15;
  symbols {
    "YARA_MALWARE"        { weight = 8.0; }  # malware family / webshell / RAT / APT
    "YARA_EXPLOIT"        { weight = 7.0; }  # exploit / CVE / maldoc exploit
    "YARA_PHISHING"       { weight = 5.0; }  # phishing kit or document
    "YARA"                { weight = 4.0; }  # matched, but uncategorized
    "YARA_SUSPICIOUS"     { weight = 2.0; }  # heuristic / suspicious (FP-prone)
    "URLHAUS_MALWARE_URL" { weight = 8.0; }  # URL in the mail is a known malware link
  }
}

So a real malware sample lands around 8 and a fuzzy heuristic adds a gentle 2, and they stack if both fire. The classifier is just a heuristic in the plugin, so retuning the buckets or the weights is a config edit and an rspamd reload — no rebuilding the scanner.

Whatever weights you pick, do the boring part first: run the tiers at weight 0.0 against live traffic, watch the rspamd history for a week or two, see what fires, and confirm the false positives are gone. Weight zero means the symbol still shows up in the history — you see exactly what’s matching, in which tier — and it adds nothing to the score. It blocks nothing. Detection before enforcement, every single time. It’s the same discipline as rolling out any rule engine: when I wrote up installing ModSecurity and the OWASP Core Rule Set on NGINX, the entire first phase was “run it in detection-only mode and read the logs.”

Where this leaves you

Three moving parts: a Go daemon that scans bytes against rules and caches the answers, a pile of public rules baked in and refreshed daily, and a Lua plugin that lets rspamd ask without blocking. None of it exotic — the same out-of-process pattern rspamd already uses for the collaborative networks, applied to a tool it forgot to include.

The code is open. yarad lives on GitHub — see its status & roadmap for what’s implemented and what’s next. Its collaborative-filtering sibling gozer is right next door, and the rspamd DCC/Razor/Pyzor backend shows the same pattern in a fuller deployment. Take them, break them, send patches.

Frequently asked questions

Related reading

• Rspamd explained: how modern spam filtering actually works. Bayes, neural nets, RBLs, and the collaborative networks YARA sits alongside.
• Olefy and rspamd: scan Office macro malware in your mail. The same out-of-process pattern, pointed at VBA macros in attachments.
• How to install ModSecurity and OWASP CRS on NGINX. The same detection-before-enforcement discipline, applied to a web application firewall.
• Docker hardening for self-hosters. Rootless, read-only, cap-drop and distroless, which is how yarad ships.
• Valkey explained: the Redis fork that actually won. The shared cache backend yarad uses across replicas.

So we did the thing that actually fixes it: we rewrote all three clients from scratch in Go and linked them into one static binary. No fork(), no interpreter start per message, no Perl or Python or set-UID C binary anywhere near your mail. Just Go code that speaks each wire protocol byte-for-byte identically to the original, answers rspamd over a single non-blocking HTTP call, and ships as a ~6 MB distroless image instead of a 268 MB one. This is the story of that port, and why it looks the way it does.

The thing is rspamd-dcc-razor-pyzor: a standalone Docker backend that runs all three networks in-process in one Go binary — gozer — and answers rspamd over one HTTP endpoint, plus the Lua plugin that talks to it. The image runs no rspamd of its own. Yours stays exactly where it is.

Why rspamd needs a sidecar for Razor and Pyzor

rspamd has a built-in DCC module. Good. It has nothing for Razor, and nothing for Pyzor. That’s the gap, and the obvious way to close it is a trap: write a tiny Lua rule that shells out to razor-check, watch it work in testing, ship it. Then traffic ramps and rspamd’s worker — the one event loop doing all the scanning — parks itself on a blocking read() waiting for a Razor server abroad to answer. While it waits it does nothing else. Not your message, not anyone else’s.

rspamd’s whole design is the opposite of that: it fires DNS, RBL and module checks concurrently and stitches the answers back as they land. One synchronous shell-out punches a hole straight through that model. The fix is old and boring — don’t do slow work in the hot path. Move the clients out of the worker, put an HTTP boundary in front of them, and let the plugin make a normal non-blocking request like every other rspamd module. One request out, three networks queried behind it, and the event loop never stops turning. rspamd logs it as a “slow asynchronous rule,” which sounds alarming and is actually the system telling you it’s working: slow, yes, but asynchronous, so nothing waits on it.

DCC, Razor and Pyzor, and what each one actually knows

If you’ve never met these three, here’s the short version. They’re collaborative-filtering networks, and they all answer a different flavour of the same question: “have a lot of other people seen this exact message too?” Spam is bulk by nature — the thing that makes it profitable, blasting one message to ten million inboxes, is also the thing that gives it away.

DCC (Distributed Checksum Clearinghouse) counts. It hashes the fuzzy “bulk” body and asks the network how many times that checksum has been reported. A personal email scores one; a newsletter to a million people scores in the millions. DCC doesn’t say “spam,” it says “bulk” — and it’s the fastest of the three, a single lean UDP round-trip.

Razor (Vipul’s Razor) is signatures. It computes a fuzzy fingerprint and checks it against a collaboratively maintained catalogue of known spam. It’s the slowest of the trio, because a check is a multi-step conversation — discovery, greeting, server state, then the lookup.

Pyzor is the same idea in different clothes: a digest of the message against a public server that counts sightings and whitelist hits — and in practice the quickest to answer.

None of these replaces your Bayes classifier or your RBLs. They’re a separate layer of evidence, and they catch the one thing statistical filters are weakest on: brand-new spam that’s textually clean but going out in enormous volume. For the full map of where these sit in a modern stack, we wrote it up in Rspamd Explained. This post is about wiring three of those layers in without setting your scanner on fire.

One Go binary, three protocols, zero forks

The first version was a Python shim, spamcheck_shim.py, that forked the perl razor-check, the python pyzor and the C dccproc once per message. It worked, but it dragged a perl + python + dcc toolchain and an s6 supervisor into the image, and every check paid an interpreter start (plus a set-UID dccproc). So all three clients were rewritten from scratch in Go and linked straight into the backend:

• gdcc — a clean-room Go DCC client; computes the message checksums byte-for-byte identically to dccproc.
• gazor — a Go Razor2 client; speaks the discovery/signature protocol of the perl razor-agents.
• gyzor — a Go Pyzor client; reproduces the SHA1 digest of the python client.

Each speaks its wire protocol byte-for-byte compatibly with the reference perl/python/C client, and each is gated by parity tests against the real razor, pyzor and dccproc in its own CI — so the servers see identical fingerprints and the switch is invisible on the wire. gozer imports all three (it lives in its own repo, pulled into the image build as a submodule), listens on :8077 as a non-root user, and on each /check runs the three networks concurrently in-process: no subprocess, no fork, no stdin pipe. A single /check still costs you roughly the slowest backend, not the sum — Razor sets the pace; DCC and Pyzor finish in its shadow.

What disappeared is the entire scaffolding: no s6 supervisor, no shell, no Perl or Python runtime, no dcc package and no set-UID dccproc, no dccifd daemon (gozer’s DCC client talks to the servers directly). The image is FROM a distroless/static base with gozer as the entrypoint, and it dropped from about 268 MB to roughly 6 MB — with no interpreter left in the message-parsing path, and nothing running as root over attacker-controlled bytes. That’s the real payoff of the Go port: not just speed, but an image with almost nothing left in it to attack.

The design rule we care most about is best-effort. Every backend can fail on its own without taking the others, or the container, down. If Razor’s servers fall off the internet at 3 a.m., gozer shrugs, returns whatever DCC and Pyzor had, and the healthcheck stays green because it only depends on gozer’s own /health (probed by gozer health, since the distroless image ships no shell or curl). A dead network degrades your scoring; it doesn’t degrade your availability.

The message never touches disk

This is the part we’d argue with you about. gozer keeps the message in memory and computes every checksum in-process. Nothing gets written to a temp file — not in /tmp, not in a tmpfs, not anywhere. Every spool file is a tiny liability: a window where the plaintext of someone’s email sits on a filesystem, waiting for a backup job to copy it, a log to mention it, or a forensic tool to find it after you thought it was gone. The cleanest way to never leak a temp file is to never write one.

The cache follows the same rule: it stores sha256(body) → verdict and nothing else. The hash, not the body. Point it at Redis instead of memory and the property holds — the shared cache stores hashes too, never content. And no, a tmpfs overlay would do nothing for speed here: there is no per-message disk write to accelerate, because there isn’t one. The latency is network round-trips to DCC, Razor and Pyzor, full stop.

The only thing that ever leaves the container is what collaborative filtering fundamentally needs: content fingerprints — DCC checksums, Razor signatures, Pyzor digests. Not the message. The networks get a hash of what your mail looks like, never the mail itself (and on a spam report, a submission, which is the entire point of reporting).

Hardening, because the defaults will get you fired

Every default in container-land is tuned for “does the demo work,” not “will this survive a hostile internet.” So the bundled compose ships the opposite. gozer runs non-root with bounded concurrency (GOZER_MAX_CONCURRENT defaults to 8), and every POST is token-authenticated: send the secret as Authorization: Bearer <token> or X-DRP-Token: <token>, get a 401 if it’s wrong. The detail we’re proud of: if you forget to set a token at all, gozer doesn’t fail open — it returns 503 to every POST and refuses to do anything. A spam backend that accepts unauthenticated “report this as spam” calls from anywhere on your network is a poisoning vector with a bow on it.

The compose file also runs the container read-only, with cap_drop: ALL, no-new-privileges, and no published host port. Read that last one twice: the backend is reachable only by containers on the same Docker network, by service name. It is not one iptables mistake away from the public internet. If you’ve ever found a Redis open to the world because someone published a port “just to test,” you know why that matters — the test port is forever. None of this is exotic; it’s the baseline every container that touches untrusted input should run with, and turning the safety on costs you four lines of YAML.

Performance and the cache that earns its keep

Numbers, measured from the build host against the public servers (anonymous; your mileage varies with distance): Pyzor about 50 ms, DCC about 170 ms, Razor about one second — Razor’s multi-step discovery handshake dominates. gozer queries all three concurrently, in-process, so a cold /check costs you roughly the Razor figure, and as an asynchronous rule that latency never blocks the scanner.

Here’s where it gets good, precisely because spam is bulk: the same campaign hits your server over and over, same body, a thousand recipients in an hour. gozer caches verdicts keyed on sha256(body), with a 300-second TTL (GOZER_CACHE_TTL) and a 4096-entry LRU (GOZER_CACHE_SIZE) by default. The first copy of a bulk body pays the full cold cost; every copy after it, within the TTL, comes back in well under a millisecond — the in-process cache hit is about 55 nanoseconds with zero allocations, flagged with X-DRP-Cache: hit in the response. No fork, no CLI, no round-trip, no concurrency slot consumed.

That’s the whole game on bulk traffic. In a synthetic end-to-end benchmark driving the full request path (auth, the concurrency gate, the cache, single-flight de-duplication and dispatch), gozer sustains roughly 30,000 checks per second at a 90% cache-hit ratio — where the backends see only about one message in nine — versus about 12,000 per second when every check misses. The property that makes the spammer’s life cheap makes your scanner’s life cheap too. Running more than one scanner? Point GOZER_REDIS_URL at a shared Redis or Valkey and every scanner shares one cache; the first box to see a campaign warms it for all of them. /report and /revoke are never cached, because reporting is a side effect you don’t want to silently swallow.

Wiring it up: backend, plugin, and Dovecot feedback

Three pieces. The backend container, the rspamd plugin, and the optional Dovecot reporting glue. Take them in order.

The backend

gozer refuses every POST until it has a token, and it isn’t published to the host, so the only sane way to run it is with the bundled compose:

cd docker
mkdir -p secrets && openssl rand -hex 32 > secrets/drp_token.txt
docker compose up -d

Containers on the same Docker network now reach it at http://rspamd-drp:8077. The image is on Docker Hub as eilandert/rspamd-dcc-razor-pyzor if you’d rather pull than build. Test it by POSTing a raw message (--data-binary keeps the bytes intact, since the fingerprints are computed over them):

TOKEN=$(cat docker/secrets/drp_token.txt)

# scan a message
curl -s --data-binary @message.eml \
  -H "Authorization: Bearer $TOKEN" http://rspamd-drp:8077/check
# {"dcc":{"action":"unknown","bulk":null},"razor":{"hit":false},"pyzor":{"count":42,"wl":0}}

# user feedback — X-DRP-Token works in place of the Bearer header
curl -s --data-binary @spam.eml -H "X-DRP-Token: $TOKEN" http://rspamd-drp:8077/report
curl -s --data-binary @ham.eml  -H "X-DRP-Token: $TOKEN" http://rspamd-drp:8077/revoke

The plugin

The Lua plugin is not baked into the backend image, on purpose: it belongs in your rspamd, not in this one. Drop it in and tell it where the backend lives:

cp rspamd/plugins/dcc_razor_pyzor.lua  /etc/rspamd/plugins/
cp rspamd/local.d/dcc_razor_pyzor.conf /etc/rspamd/local.d/
cp rspamd/local.d/groups.conf          /etc/rspamd/local.d/
echo 'dofile("/etc/rspamd/plugins/dcc_razor_pyzor.lua")' >> /etc/rspamd/rspamd.local.lua

Then set the backend URL and the same token in local.d/dcc_razor_pyzor.conf:

url   = "http://rspamd-drp:8077/check";
token = "the-shared-secret";

Restart rspamd and you get three new symbols, scored in groups.conf: DRP_DCC_BULK when DCC says the body is bulk, DRP_RAZOR on a Razor signature match, and DRP_PYZOR when Pyzor sightings clear the threshold.

One gotcha that will eat your afternoon: rspamd resolves URLs through its own configured resolver, not the system one. If you’ve pointed it at an RBL-only unbound that can’t see Docker service names, rspamd-drp won’t resolve and you’ll get a confusing silence rather than a clean error. The fix is to put the backend’s IP in url instead of the service name. It’s always DNS. It’s genuinely always DNS.

Dovecot feedback

/check is for scanning. /report and /revoke are for human feedback: someone drags a message into Junk (spam, report it) or rescues one back out (ham, revoke it). Real human corrections are the best signal you’ll ever get. Sieve can’t speak HTTP, so a little wrapper called drp-report bridges the gap, triggered by imapsieve; the eilandert/dovecot image already bakes it in. On any other Dovecot host you copy three files, compile two sieve scripts, and drop the URL and token into an env file (sieve scrubs the environment, so it can’t come from a shell variable). Move into Junk fires POST /report; move out fires POST /revoke. And drp-report always exits 0, on purpose, so a reporting hiccup never bounces a message or blocks the IMAP move — the worst case is one un-reported spam, not a stuck mailbox.

Where this fits with the rest of the spam stack

Collaborative filtering is one layer, not the layer. It answers “is this bulk” and “has the crowd flagged this,” and it’s brilliant at catching high-volume campaigns the instant they start — and nearly useless against a targeted message sent to you and only you, because there’s no crowd to have seen it yet. That’s why it pairs so well with rule-based scoring, which catches the textual tells a single message gives off regardless of volume. The other half of our setup is rspamd-kam-rules, a native-Lua converter that brings 3,200-odd SpamAssassin KAM.cf rules into rspamd without the Perl spamassassin module; we wrote that up in KAM.cf in Rspamd. Rules catch the content signature, DCC/Razor/Pyzor catch the volume, Bayes catches the statistical drift, and between them very little gets through.

Everything’s open: gozer and the deployment repo on GitHub, the gdcc / gazor / gyzor Go clients each in their own repo, the image on Docker Hub, and the lot tracked in the dockerized monorepo. The full list of repos and images lives on the where to find us page.

Frequently asked questions

Coraza WAF is the answer to the obvious next question: what runs the CRS when ModSecurity finally stops? It’s a clean-room rewrite of the whole engine in Go, it reads your existing SecRule files without translation, and we package it for Debian and Ubuntu as a pair of .debs plus an NGINX dynamic module. This is the tour: what Coraza WAF is, why a Go firewall needs a C library bolted to its side, and when to pick it over the engine it replaces.

What Coraza WAF actually is

A web application firewall sits in front of your app and reads every request before your code does. SQL injection in a query string, a path-traversal ../../etc/passwd in a URL, a known exploit payload aimed at some WordPress plugin: the WAF matches it against a ruleset and blocks, logs, or scores it before your PHP ever wakes up. ModSecurity invented this pattern for the open web. The OWASP Core Rule Set (CRS) is the big free ruleset everyone uses on top of it.

Coraza is a from-scratch reimplementation of that engine in Go. Not a wrapper, not a port: a new codebase that happens to speak the same dialect. It implements the SecLang rule language, the same one you’ve been writing as SecRule REQUEST_URI "@rx evil" "id:1,phase:1,deny" for twenty years. It runs the OWASP CRS unmodified. If you already have a ModSecurity config, most of it drops straight in.

The reason it exists in Go and not C++ is the reason half of you already guessed. Memory safety. ModSecurity is a C++ codebase parsing hostile, attacker-controlled input on the hottest path in your stack, which is exactly the place you least want a buffer overflow.

A WAF with a memory-corruption bug is worse than no WAF: now the thing meant to stop the attacker is the attacker’s way in. Go won’t hand you a use-after-free in the request parser. That single property is most of the pitch.

Here’s the catch, and it’s the whole reason this article isn’t two sentences long. Go is a garbage-collected language with its own runtime and its own scheduler. NGINX is C. You cannot simply call Go from C the way you call a normal library. Bridging those two worlds is what the C library in the next section exists to do.

libcoraza: why a Go firewall needs a C library

NGINX speaks C. The Coraza engine is Go. Something has to translate, and that something is libcoraza: a thin C-bindings layer that compiles the Go engine into a C-callable shared object using cgo and Go’s c-shared build mode. The output is a real libcoraza.so with a header full of honest C functions: coraza_new_transaction, coraza_process_request_headers, coraza_process_response_body, and the rest. Your C code calls those. Inside, the Go runtime does the actual work.

We package libcoraza on its own, exactly like we package libmodsecurity3 for the old engine. Two binary packages come out of it:

• libcoraza1: the runtime shared library, libcoraza.so.1, what your server actually loads.
• libcoraza-dev: the header (coraza.h) and the unversioned libcoraza.so symlink, needed only at build time to compile something against it.

Building it is its own small adventure. The library needs the Go toolchain (currently Go 1.25), autotools, libtool, and a C compiler, because it’s a cgo build wrapped in an autoconf shell. That Go version requirement matters more than it looks, and I’ll come back to it when we talk about which distros get the module at all.

libcoraza also ships a SWIG interface file, which means the same C-callable engine can generate bindings for Python, Ruby, Java, PHP, and Perl. We don’t ship those. But it’s a nice reminder that this isn’t an NGINX-only project. libcoraza is the front door for embedding Coraza in any C-speaking application, and NGINX is just our first guest.

The nginx-coraza connector and its four directives

On top of libcoraza sits the actual NGINX module, ngx_http_coraza_module, built from the coraza-nginx connector. It’s a fork of the old ModSecurity-nginx connector, which is why the wiring feels familiar if you’ve ever run ModSec on NGINX. The module is the plumbing between NGINX’s request lifecycle and libcoraza’s transaction API: it hands each request’s headers, body, and response over to the engine at the right phase and acts on the verdict.

It adds four config directives, and that’s the whole surface area:

• coraza on|off;: the master switch. Works in http, server, and location blocks, defaults to off. Turn it on where you want inspection, leave it off for your static asset locations so you’re not running the CRS against every favicon request.
• coraza_rules_file /path/to/rules.conf;: point it at a rules file. This is where you load the CRS.
• coraza_rules 'SecRuleEngine On ...';: inline rules straight in the NGINX config, handy for one or two per-location tweaks without a whole file.
• coraza_transaction_id $some_var;: feed it NGINX’s own request ID so your WAF logs and your access logs share a key. When you’re correlating “what did the WAF do to request X” against your access log at 3 a.m., this is the line that saves you.

A minimal server looks like this:

server {
    coraza on;
    coraza_rules_file /etc/nginx/coraza/coraza.conf;

    location / {
        root /var/www/html;
    }
}

The inheritance is the bit worth memorising. Rules merge parent-then-child: a coraza_rules_file in the server block applies everywhere, and a location block with its own rules gets the parent’s rules prepended to its own. A location with no rules of its own just shares the parent set. So you set the CRS once at the server level and only add per-location overrides where a specific app genuinely needs them. Predictable, top-down, no surprises. The way config inheritance should work and frequently doesn’t.

Coraza WAF vs ModSecurity: which one do you actually want

We package both. libmodsecurity3 with its NGINX connector, and Coraza with this one. They run the same OWASP CRS. So which?

ModSecurity v3 (libmodsecurity) is the battle-tested incumbent. It has been in production on more sites than anyone can count, the CRS is tuned against it first, and every Stack Overflow answer about a weird false positive assumes it. It’s C++, which means it’s fast and it means a parser bug is a memory-safety bug. It’s also in maintenance mode now that ModSecurity proper has been handed off, so the long arc bends away from it.

Coraza is the future-facing pick. Memory-safe by construction, actively developed, designed from day one to be embeddable beyond NGINX. The tradeoff is the cgo/Go-runtime bridge: a slightly heavier per-worker footprint because every worker carries its own copy of the Go runtime. For most sites that cost is invisible. If you’re running a thousand workers on a memory-starved box, measure it.

Here’s my actual opinion, and you can disagree. For a new deployment in 2026, start with Coraza. The memory-safety argument on the single most attacker-exposed component in your stack is the one that wins, and “the CRS is tuned against ModSec first” matters far less than it used to because the CRS team treats Coraza as a first-class target now. Keep ModSecurity if you have years of finely-tuned exclusions you don’t want to revalidate. That tuning is real work and throwing it away to chase a newer engine is its own kind of foolish.

Either way, the WAF is one layer. It is not your security plan. A WAF in front of an unpatched app buys you time, not safety, and anyone who tells you otherwise is selling something.

How we package it, and why only some distros get it

Our build produces a clean dependency chain. libcoraza builds first and publishes to the apt repo: libcoraza1 and libcoraza-dev. Then NGINX builds, with libcoraza-dev as a build dependency (it needs coraza.h to compile the connector) and libcoraza1 as the runtime dependency of the resulting libnginx-mod-http-coraza package. Order matters: if libcoraza isn’t in the repo yet, the NGINX build aborts at dependency resolution before it even starts. Build the library, publish it, then build NGINX. The same applies to our Angie packages, which carry the module as angie-module-http-coraza.

There’s a deliberate limit on which distributions get the module: trixie and resolute only. No bullseye, no bookworm, no jammy, no noble. The reason is that Go 1.25 requirement from earlier. libcoraza needs golang-1.25 to build, and only Debian trixie (with backports, which is what resolute tracks) ships it. Older releases simply don’t have a new enough Go, so the library can’t be built there, so the module can’t exist there. We gate it with Debian build profiles rather than architecture restrictions, because this is a “which release” decision, not a “which CPU” one. On amd64 and arm64 alike, trixie and resolute get Coraza; everything older gets the ModSecurity package and a shrug.

Turning it on with the OWASP CRS

A real config loads the recommended Coraza base config and then the CRS on top. The base config sets the engine on and configures body inspection limits; the CRS brings the actual attack rules. Roughly:

http {
    # one master switch, inherited by every server below
    coraza on;
    coraza_rules_file /etc/nginx/coraza/coraza.conf;
    coraza_rules_file /etc/nginx/coraza/coreruleset/crs-setup.conf;
    coraza_rules_file /etc/nginx/coraza/coreruleset/rules/*.conf;

    server {
        listen 443 ssl;
        server_name example.com;

        location /assets/ {
            coraza off;   # don't run the CRS against static files
        }
    }
}

Start in detection-only mode. The CRS ships with SecRuleEngine DetectionOnly for a reason: turn it loose in blocking mode on a real app on day one and you will block your own admins, your own API, and probably your own healthcheck inside the hour. Run it in detection mode, watch the logs for a week, build your exclusions for the false positives, then flip to SecRuleEngine On. The trailing slash on those location paths matters; yes, it always does; no, nobody is happy about it.

When something does get blocked and you need to know which rule did it, this is where that coraza_transaction_id directive earns its keep. libcoraza 1.6 added the ability to surface the matched rule’s ID through the API, so your logs can tell you “rule 942100 fired” instead of “something somewhere said no”. Wire the transaction ID to NGINX’s $request_id and you can pivot from an access-log line straight to the WAF decision for that exact request. Future you, mid-incident, will be grateful.

If you’ve set up ModSecurity and the CRS on NGINX before, none of this will feel foreign, and our step-by-step ModSecurity and OWASP CRS guide maps almost directly onto Coraza. Swap the engine, keep the rules.

Migrating from ModSecurity to Coraza, step by step

So you already run ModSecurity v3 with the CRS on NGINX, and you want to move to Coraza without taking your site down or throwing away years of tuning. Good news: because both engines speak SecLang and run the same OWASP CRS, this is a config-swap, not a rewrite. The rules come with you. Only the wiring changes. Here is the order I’d do it in, the boring careful way, because the exciting careless way ends with you blocking your own login page at 2 a.m.

Step 0 — Inventory what you already have

Before you touch anything, write down what ModSecurity is currently loading. The three things that matter: your base config (the modsecurity.conf with SecRuleEngine, body limits, audit log settings), your CRS install (which version, the crs-setup.conf, the rules/*.conf), and — the valuable part — your exclusions. Those are the SecRuleRemoveById, ctl:ruleRemoveTargetById, and custom allow rules you bled for over months of false positives. That tuning is the whole reason you’re nervous about migrating. It’s also the part that ports across completely unchanged.

# find what your current modsec setup pulls in
grep -rhE 'Include|modsecurity_rules_file' /etc/nginx/ /etc/modsecurity/ 2>/dev/null
ls -la /etc/modsecurity/ /etc/nginx/modsec*/ 2>/dev/null

Step 1 — Install the Coraza packages alongside, not instead

You do not remove ModSecurity yet. Both modules can be installed at once; you just don’t load both for the same traffic. On trixie or resolute:

apt update
apt install libnginx-mod-http-coraza   # pulls in libcoraza1 automatically
# Angie users:
apt install angie-module-http-coraza

If apt can’t find it, you’re on the wrong release — Coraza is trixie/resolute only, for the Go 1.25 reason covered above. Older boxes stay on ModSecurity; there is no migration target for them yet.

Step 2 — Lay down the Coraza base config and bring your CRS over

Coraza ships a recommended base config (coraza.conf-recommended) that mirrors ModSecurity’s modsecurity.conf-recommended. Copy it, then drop your existing CRS directory in next to it. You do not need to re-download the CRS — the exact files you feed ModSecurity work as-is:

mkdir -p /etc/nginx/coraza
cp /etc/nginx/coraza/coraza.conf-recommended /etc/nginx/coraza/coraza.conf

# reuse the CRS you already have — copy or symlink it in
cp -r /etc/modsecurity/coreruleset /etc/nginx/coraza/coreruleset
cp /etc/nginx/coraza/coreruleset/crs-setup.conf.example \
   /etc/nginx/coraza/coreruleset/crs-setup.conf   # if not already done

This is the part people don’t believe until they see it: your crs-setup.conf, your paranoia-level setting, your anomaly thresholds, all of it carries over byte-for-byte. The CRS doesn’t know or care which engine is reading it.

Step 3 — Port your exclusions (the bit that actually matters)

Your hand-tuned exclusions are SecLang too, so they move across verbatim. If you kept them in a REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf / RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf pair (the CRS-recommended layout), just copy those files in alongside the CRS and load them in the same before/after order. If instead you’d been using our CRS plugins — wordpress-hardening-plugin, vaultwarden-crs-plugin, vimbadmin-crs-plugin — even better: they’re engine-agnostic, so you copy the same plugin directory and load it the same way. No re-tuning, no revalidation. That’s the entire payoff of staying inside the CRS ecosystem instead of inventing your own rules.

Step 4 — Swap the NGINX wiring

This is the only genuinely new part. ModSecurity’s connector used modsecurity on; and modsecurity_rules_file; Coraza uses coraza on; and coraza_rules_file. Same shape, different prefix. Comment out the old directives, add the new ones. Load order is base config → CRS setup → CRS rules → your exclusions, exactly as before:

load_module modules/ngx_http_coraza_module.so;   # in the main context

http {
    # --- old, leave commented until cutover is proven ---
    # modsecurity on;
    # modsecurity_rules_file /etc/nginx/modsec/main.conf;

    # --- new ---
    coraza on;
    coraza_rules_file /etc/nginx/coraza/coraza.conf;
    coraza_rules_file /etc/nginx/coraza/coreruleset/crs-setup.conf;
    coraza_rules_file /etc/nginx/coraza/coreruleset/rules/*.conf;
    coraza_transaction_id $request_id;   # so WAF logs join your access logs
}

Step 5 — Detection-only, for a week, no exceptions

Set SecRuleEngine DetectionOnly in your Coraza base config and reload. Yes, even though you already tuned this exact ruleset under ModSecurity. The engines are not bit-identical: Coraza’s parser and a few operators behave subtly differently on edge cases, so a rule that never fired under ModSec might find something new, and vice versa. Run both engines’ logs side by side for a week and diff the verdicts. If Coraza blocks something ModSecurity let through (or the reverse), that’s your short list to investigate before cutover.

nginx -t && systemctl reload nginx
# watch what Coraza would have done
tail -f /var/log/nginx/error.log | grep -i coraza

Step 6 — Cut over, and keep the rollback one line away

Once the detection-mode logs are clean and match your expectations, flip Coraza to SecRuleEngine On, reload, and watch live for a few hours. The beauty of leaving the old ModSecurity directives commented rather than deleted is your rollback is uncommenting four lines and a reload — under a minute, no reinstall. Once Coraza has run clean in blocking mode for a week or two, then you remove the ModSecurity module and config for good. Not before. There is no prize for deleting the safety net early.

Frequently asked questions

Our OWASP CRS plugins

The CRS supports plugins: drop-in rule bundles that tune the base rules for one specific app, killing its false positives and adding app-aware hardening without forking the rule set. They work the same whether the engine underneath is Coraza or ModSecurity. We maintain three:

• wordpress-hardening-plugin: locks down the usual WordPress attack surface (wp-admin, xmlrpc, REST, login) and clears the CRS false positives the block editor and plugin updates would otherwise trip.
• vaultwarden-crs-plugin: exclusions for the Vaultwarden / Bitwarden API so the CRS stops flagging legitimate encrypted vault traffic as an attack.
• vimbadmin-crs-plugin: exclusions for ViMbAdmin, the mail-domain admin panel, so its forms survive a paranoid CRS in blocking mode.

Related reading

• How to Install ModSecurity and OWASP CRS on NGINX: the older engine, same rule set, step by step. The closest map to a Coraza setup.
• What Is the BREACH Attack?: a compression side-channel a WAF won’t save you from, and what actually does.
• Docker Hardening for Self-Hosters: defence in depth below the WAF: rootless, read-only, cap-drop.

Anyway. Before you flip SecRuleEngine On in production, mirror your traffic to a detection-only box for a week. The CRS will block something you depend on. It always does.

That’s the pitch for TLS fingerprinting, and it’s a good one. A Python requests script can set User-Agent: Mozilla/5.0 ... Chrome/120 all day long. It cannot easily forge the byte-level shape of a real Chrome handshake, because that shape comes from the TLS library underneath, not the string you type into a header. So a bot pretending to be a browser usually fails the handshake-shape test even while it passes the header test. That’s why fingerprinting works, and that’s why people want to block on it. Whether you should block on it is the part nobody warns the juniors about, and it’s where this post spends most of its time.

We’ll use Hanada Lee’s ngx_ssl_fingerprint_module as the concrete example, because it’s the cleanest current implementation for nginx and it exposes JA3, JA3 hash, and the full JA4 family as plain nginx variables you can log, match, and (if you’re brave) reject on.

What a TLS fingerprint actually is

Here’s what’s happening on the wire. When a client opens a TLS connection, the first thing it sends is the ClientHello. It’s a structured blob that says, roughly: “I speak TLS version X, here are the cipher suites I support in this order, here are the extensions I’m sending in this order, here are the elliptic curves I like, and here are the signature algorithms I’ll accept.” None of that is secret. All of it is necessary for the handshake to work. And all of it is wildly inconsistent between different TLS stacks.

Chrome’s BoringSSL sends a different cipher list, in a different order, with a different extension layout than OpenSSL, than Go’s crypto/tls, than Python’s ssl module, than curl, than Java. The ordering matters as much as the contents. Two libraries can support the exact same 15 cipher suites and still be told apart instantly because one lists them oldest-first and the other newest-first. That ordering is baked into the library at compile time. The script kiddie spoofing a User-Agent string never touches it.

A fingerprint is just a deterministic recipe for turning that ClientHello into a short, comparable string. Feed the same client through the recipe twice, you get the same string. Feed a different stack through it, you get a different string. The recipe is public. The discriminating power comes from the fact that the inputs are stable per-software and varied across-software.

JA3: the original, and where it bleeds

JA3 was the first widely-adopted version, and the recipe is simple enough to do on a napkin. You take five fields from the ClientHello: the TLS version, the list of cipher suites, the list of extensions, the list of elliptic curves, and the list of EC point formats. You concatenate their decimal values with commas, glue the five groups together with dashes, and you get a string like this:

769,4865-4866-4867-49195-49199-...,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-21,29-23-24,0

Then you MD5-hash that string down to something like e7d705a3286e19ea42f587b344ee6865. That hash is the JA3. Short, loggable, easy to compare against a blocklist of known-bad bots. Salesforce shipped it, threat-intel feeds adopted it, and for a few years it was the bot-detection darling.

And then it started bleeding, for two reasons that will page you at 3 a.m. if you trusted it too hard.

First: MD5. Not for the cryptographic reasons (collisions don’t matter here, nobody’s attacking the hash) but because once you’ve hashed the string you’ve thrown away all the structure. You can’t look at e7d705a3... and reason about why two clients differ. It’s opaque. You either have it in your blocklist or you don’t.

Second, and worse: GREASE. Chrome and other modern browsers deliberately inject random junk values into their cipher and extension lists. RFC 8701, “Generate Random Extensions And Sustained Extensibility”, exists so that middleboxes don’t ossify the protocol by assuming the list of valid values never grows. The browser tosses in a reserved GREASE value (0x0a0a, 0x1a1a, and friends) that means nothing, and a correct server ignores it. But naive JA3 includes those random values in the hash. So the same Chrome install produces a different JA3 on every single connection, because the GREASE value rotates. Your blocklist of “known bad JA3 hashes” is now playing whack-a-mole against noise. Implementations learned to strip GREASE before hashing, but the spec never said they had to, so you get inconsistent JA3 values depending on whose code computed them. Great.

JA4: same idea, fewer foot-guns

John Althouse went back to the drawing board and released the JA4+ family in 2023 under a more permissive license than the original drama around JA3 allowed. JA4 keeps the core insight and fixes the operational mess.

The big changes. JA4 is human-readable by design. Instead of one opaque MD5, a JA4 fingerprint has visible structure: a prefix that tells you the transport (TCP or QUIC), the TLS version, whether SNI was present, the cipher and extension counts, and the ALPN value, followed by a truncated SHA-256 of the sorted cipher list and another of the sorted extension list. So a JA4 looks like t13d1516h2_8daaf6152771_b186095e22b6 and you can actually read the front of it: t = TCP, 13 = TLS 1.3, d = SNI present, 1516 = 15 ciphers / 16 extensions, h2 = ALPN says HTTP/2.

And the killer fix: JA4 sorts the cipher and extension lists before hashing. GREASE values get stripped, the rest get sorted, so the random junk and the connection-to-connection ordering jitter stop mattering. One Chrome build now produces one stable JA4, the way you always wanted JA3 to behave. This is the single most important reason to prefer JA4 over JA3 if you’re starting fresh. The sorted, GREASE-stripped fingerprint is the one that survives contact with reality.

JA4 also comes with a whole family. JA4 fingerprints the client. JA4S fingerprints the server’s ServerHello response, which is handy for fingerprinting what a backend is running. The original JA3 had a server-side sibling too, JA3S, built the same way from the ServerHello. The module we’re about to compile exposes both raw and hashed JA4 variants so you can pick readability or compactness depending on whether a human or a regex is reading the value.

Getting it into nginx: the patched-stack tax

Now the part that makes sysadmins sigh. You cannot just --add-module this thing onto a stock nginx and call it a day. TLS fingerprinting needs the raw ClientHello bytes, and stock OpenSSL doesn’t hand them to nginx. The handshake parsing happens deep inside OpenSSL, the interesting bytes get consumed, and by the time nginx’s code runs they’re gone. So ngx_ssl_fingerprint_module ships two patches: one for OpenSSL (to preserve the ClientHello during negotiation and expose it) and one for nginx (to store the computed fingerprints on the connection where the variables can reach them).

That means rebuilding nginx against a patched, statically-linked OpenSSL. You’re not using the distro’s libssl any more. The current module targets OpenSSL 3.5.4+ and nginx 1.29.3+, and the build looks like this:

git clone -b release-1.29.3 --depth=1 https://github.com/nginx/nginx
cd nginx
git clone -b openssl-3.5.5 --depth=1 https://github.com/openssl/openssl
git clone -b ja4_fingerprint https://git.hanada.info/hanada/ngx_ssl_fingerprint_module

patch -p1 -d openssl < ngx_ssl_fingerprint_module/patches/openssl.openssl-3.5.5+.patch
patch -p1 < ngx_ssl_fingerprint_module/patches/nginx-1.29.3+.patch

./auto/configure \
  --with-openssl=./openssl \
  --with-stream_ssl_module \
  --add-module=./ngx_ssl_fingerprint_module \
  --with-http_v2_module \
  --with-stream
make -j

Two things bite here. One: this is a static OpenSSL build, so every time OpenSSL ships a CVE fix (and OpenSSL ships CVE fixes the way the rest of us ship typos) you rebuild nginx, you don't just apt upgrade libssl3 and reload. You own the patch cadence now. Two: the patch is version-pinned. The OpenSSL patch is written against a specific OpenSSL source tree, and if you bump to a version it wasn't written for, it'll fail to apply or, worse, apply with fuzz and miscompile. Pin your versions, test the build in a throwaway environment, and don't do it for the first time on the box that's serving traffic.

If the idea of maintaining your own OpenSSL build makes you twitch, that's the correct instinct, and it's exactly why we ship a dedicated openssl-nginx package built just for nginx and Angie. The fingerprinting patch lives in the same world as every other "nginx needs a custom crypto stack" feature: HTTP/3, post-quantum key exchange, kTLS. Once you've accepted one, the rest are just more patches on the pile.

The variables, and a config that does something

Once it's built, you flip it on with one directive and you get a fistful of nginx variables. The directive is ssl_fingerprint on; and it works in both the http and stream contexts, which means you can fingerprint plain TCP/TLS too, not only HTTP. Off by default, because computing fingerprints on every handshake isn't free and most vhosts don't need it.

Here's the variable set:

$ssl_greased            # 1 if the client sent GREASE values (a real-browser tell)
$ssl_fingerprint_ja3    # raw JA3 string
$ssl_fingerprint_ja3_hash   # MD5 of the JA3
$ssl_fingerprint_ja4_r  # JA4 raw (full, unhashed)
$ssl_fingerprint_ja4    # JA4 standard (the readable+hashed form)
$ssl_fingerprint_ja4_ro # JA4 "original" raw (the pre-sort ordering variant)
$ssl_fingerprint_ja4_o  # JA4 "original" hashed

The _r suffix means raw (unhashed, debuggable). The _o suffix is the "original" ordering variant: JA4 normally sorts the lists, but JA4_O preserves the original on-wire order, which keeps a little more discriminating power at the cost of the GREASE-stability that sorting buys you. Use the plain $ssl_fingerprint_ja4 for blocklists and the _r / _ro raw forms when you're staring at a log trying to work out why a legit client got nuked.

A minimal config that just shows you your own fingerprint:

http {
    ssl_fingerprint on;
    server {
        listen 127.0.0.1:4433 ssl;
        ssl_certificate     cert.pem;
        ssl_certificate_key priv.key;
        return 200 "ja4: $ssl_fingerprint_ja4\nja3: $ssl_fingerprint_ja3\ngreased: $ssl_greased\n";
    }
}

The first thing any sane person does is log the fingerprint, don't block on it. Add $ssl_fingerprint_ja4 to your log_format, let it run for a week, and go look at what your actual traffic looks like before you reject a single byte. You'll learn more from one week of logs than from any threat-intel blog post. A custom log line:

log_format fp '$remote_addr "$http_user_agent" '
              'ja4=$ssl_fingerprint_ja4 greased=$ssl_greased';
access_log /var/log/nginx/fp.log fp;

From there, the obvious move is to feed the fingerprint into the same machinery you already use to deal with abusive clients. Pair it with the error-abuse module that auto-bans clients, or use it as one more signal in the broader fight to defend your webserver against vibe-coded AI exploit scanners and bots. The fingerprint is a feature, not a verdict. Treat it like one.

Why TLS fingerprinting works (and why GREASE is your friend)

The reason this whole approach has teeth is the gap between two layers. The application layer (headers, cookies, the User-Agent) is trivially forgeable because it's just strings the client chooses to send. The transport layer (the ClientHello shape) is much harder to forge because it's emitted by the TLS library, and the TLS library is compiled C that the average scraper author has no idea how to bend. A Go program using net/http emits Go's handshake. A Python requests call emits OpenSSL's handshake via CPython. Neither looks remotely like Chrome, no matter what User-Agent they paste on top.

So the highest-value check is dead simple and almost free: does the User-Agent claim to be Chrome while the JA4 fingerprint says "this is Python"? That mismatch is a screaming red flag. The header says one thing, the handshake says another, and the handshake is the one that's expensive to fake. That single contradiction catches a depressing amount of low-effort bot traffic.

And $ssl_greased is the quiet hero here. Real modern browsers send GREASE. Most scripting libraries don't bother. So a connection that claims to be a current browser but has greased=0 is suspicious before you even look at the full fingerprint. It's not proof (some libraries have started adding GREASE to blend in), but as a cheap first-pass tell it earns its keep. Remember that callback when we get to evasion: the moment a signal becomes valuable, the bots start mimicking it.

Is it safe to block on? The honest answer

No. Not on its own. Here's the part the breathless "block all bad JA3" blog posts skip, and it's the part that'll cost you real customers if you ignore it.

Fingerprints are shared by millions of people. A JA3 or JA4 fingerprint identifies a TLS stack, not a person and not a bot. Every Chrome 120 user on the same OS produces a near-identical fingerprint. That's hundreds of millions of humans behind a handful of hashes. So when you blocklist a fingerprint because some bot used it, you may be blocking that bot and also every legitimate Chrome user who happens to share its TLS library. The fingerprint has zero ability to tell those two apart, because at the TLS layer they are identical. This is the single biggest reason fingerprint blocklists backfire.

TLS libraries churn. Chrome updates roughly every four weeks, and a fair number of those updates touch the TLS stack: a new cipher, a reordered extension, a tweaked GREASE behaviour. Each change shifts the fingerprint. Your carefully-curated allowlist of "good browser fingerprints" goes stale on Chrome's release schedule, not yours. Pin too hard and you'll start blocking the newest Chrome the day it ships, which is exactly the users you least want to lose. I've watched a fingerprint allowlist turn into an outage because nobody updated it through three Chrome releases. It's always the allowlist.

Collisions cut both ways. Different browsers sometimes converge on the same fingerprint, and the same browser behind different middleboxes (corporate TLS-inspection proxies, some VPNs, certain antivirus products that MITM your HTTPS) produces a different fingerprint than the bare browser would. So your corporate users behind a Zscaler proxy don't look like Chrome any more, they look like Zscaler. Block "non-browser fingerprints" and you've just locked out every employee at a security-conscious company.

And spoofing is a solved problem for motivated attackers. Tools like utls (Go), curl-impersonate, and a pile of others exist specifically to emit a byte-perfect Chrome ClientHello from a non-Chrome client. The serious bots already use them. So fingerprinting filters out the lazy 80% (the raw python-requests and Go-http-client traffic) and does nothing to the motivated 20% who copied a real Chrome fingerprint on purpose. That's still a useful 80%. Just don't kid yourself that you've stopped the people actually worth worrying about.

So what is safe? Use the fingerprint as one weighted signal among several, never as a sole verdict. Log first, always. Score, don't ban: a UA/JA4 mismatch plus greased=0 plus a hammering request rate is a confident bot; any one of those alone is a coin flip. Rate-limit or challenge the suspicious buckets rather than hard-blocking them, so a false positive degrades to a CAPTCHA instead of a white page. And keep a human-readable record (the _r raw variants in your logs) so when a customer emails "your site won't load", you can actually see what their handshake looked like instead of guessing. Fingerprinting is a fantastic detector and a terrible judge. Wire it up accordingly.

Where this fits in a real defence

Think of TLS fingerprinting as the bouncer who clocks that your ID photo doesn't match your face. It's a fast, cheap first impression that flags the obvious fakes. It is not the metal detector, the guest list, or the security camera, and a club that ran on nothing but the bouncer's gut would get robbed weekly. Layer it. The fingerprint feeds a score; the score feeds rate-limiting and challenges; persistent abusers get auto-banned; and your underlying TLS configuration is already hardened so the handshake you're fingerprinting is a modern one in the first place.

The ngx_ssl_fingerprint_module gives you the raw material cleanly: JA3 for compatibility with old threat feeds, JA4 for the stuff that actually survives a Chrome update, JA3S/JA4S if you're fingerprinting servers, and $ssl_greased as the cheapest browser-tell you'll ever get. What it doesn't give you, and what no module can, is the judgement to know when a fingerprint is a clue and when it's a trap. That part's still your job.

Anyway. Log it for a week before you block anything, and back up your nginx config before you go anywhere near a custom OpenSSL build.

Frequently asked questions

Related reading

• How to defend your webserver against vibe-coded AI exploit scanners and bots: where fingerprinting fits in the wider bot-defence toolkit.
• Auto-ban abusive clients in NGINX with the error-abuse module: the enforcement layer your fingerprint score should feed into.
• openssl-nginx: the dedicated OpenSSL built just for NGINX and Angie: the custom crypto stack that makes patched-OpenSSL features sane to maintain.
• TLS configuration for NGINX and Angie: getting an A+ on SSL Labs: harden the handshake you are fingerprinting.

This is a build guide. By the end you’ll have an nginx page cache running inside the web server itself: no Varnish daemon, no Lua, no second port to babysit. We’ll go from a stock nginx to a tuned, fleet-shared, self-monitoring cache in nine steps, and I’ll tell you which knob pages you at 3 a.m. if you get it wrong.

First, the thirty-second version of why. Your backend is slow. I don’t care what it’s written in. PHP, Node, Python, that Rust service you’re very proud of: the moment it has to talk to a database, render a template, and stitch together a page, you’re looking at tens to hundreds of milliseconds per request. A WordPress homepage that wakes PHP-FPM, runs forty plugins, and fires a dozen MySQL queries can take 600 to 900 ms to build. nginx can hand you a saved copy out of memory in about 0.4 ms. That’s not a typo. It’s roughly a thousand to one. So you build the page once, keep it, and serve everyone else the copy. That’s a page cache, and cache-turbo is one that lives in the worker processes you already have.

Step 1: build the module

cache-turbo is a normal nginx dynamic module. Nothing exotic, no external libraries to chase:

$ ./configure --with-compat --add-dynamic-module=/path/to/nginx-cache-turbo-module
$ make modules

That drops ngx_http_cache_turbo_module.so into objs/. It compiles against both nginx and Angie. You end up with a .so and one line at the top of your config:

load_module modules/ngx_http_cache_turbo_module.so;

One detail the README is quiet about and I’m not: the Redis client (Step 6) is hand-rolled on nginx’s own event loop. No hiredis, no blocking socket calls parked in the middle of your event-driven server choking every other connection on the worker. That’s why there’s nothing to apt install alongside it. Bolting a synchronous client into an async server is how you turn a fast server into a slow one with extra steps, and somebody always tries it.

Step 2: declare a shared-memory zone

The cache needs a slab of RAM to live in. You declare it once, in the http block, and name it:

http {
    cache_turbo_zone name=ct 256m;
    ...
}

This is your L1, and it’s the whole game on a single server. It’s an mmap‘d region the worker processes share, holding an rbtree keyed on a hash of each request, with LRU eviction once it fills. A hit here never leaves the worker. It’s per-box: every nginx server has its own L1, and they don’t know about each other until you add Redis.

Size it for your hot set, not your whole site. 256 MB holds a lot of HTML. If you’re caching a million long-tail URLs that each get one hit a week, you’ve misunderstood the tool: that’s a job for disk, and we’ll stack the two in a moment. Watch the eviction counter (Step 8) to know if you guessed too small.

Step 3: turn caching on, and meet stale-while-revalidate

Now bind the zone inside a location and give it a freshness window:

server {
    listen 80;
    location / {
        cache_turbo       ct;
        cache_turbo_valid 60s;
        proxy_pass http://127.0.0.1:8080;
    }
}

That’s a working cache. But the interesting behaviour is what happens when a copy gets old, and this is the part worth tattooing somewhere.

A cached copy has three life stages. While it’s young it’s fresh: served instantly, backend stays asleep. Once it passes the TTL it goes stale, and here’s the move: cache-turbo keeps serving the old copy immediately while it sends exactly one request off in the background to fetch a new one. Nobody in the queue waits. When the copy gets truly ancient it’s expired, and only then does cache-turbo treat it as a miss and make someone wait.

That middle stage is stale-while-revalidate, SWR for short. The naive alternative, the one every junior writes first, is “when the cache expires, the next request rebuilds it.” Sounds reasonable. It’s a trap. Picture your most popular page expiring at noon. At noon plus one millisecond, a thousand requests arrive, all see an empty cache, and all charge at your backend simultaneously to rebuild the same page. That’s a thundering herd, also lovingly known as a cache stampede or the dogpile. I’ve watched one take down a database that was, on paper, massively over-provisioned. The post-mortem was short. “It’s always the cache.” Right next to “it’s always DNS.” SWR kills the herd because nobody ever stares at an empty slot. (If you want the formal version, serve-stale is codified in RFC 9111, the HTTP caching spec.)

The dice and the beta knob

When exactly does cache-turbo refresh a stale copy? Not the instant it goes stale (a page that gets one hit an hour shouldn’t refresh the microsecond it expires). It rolls dice, and the dice get loaded the longer the copy has been stale. The model is a linear ramp across the stale window: probability zero the moment it goes stale, effectively one by the time it’s about to expire. Every reader rolls independently, so a barely-stale page almost always gets served as-is and a nearly-expired one almost certainly triggers a refresh.

The cache_turbo_beta directive scales how eager that ramp is. It’s fixed-point integer math (beta times 1000, so no floats in the hot path; the people who’ve profiled nginx workers know why that matters). At beta=1000 the probability tracks the elapsed fraction directly. Crank it to 2000 and pages refresh earlier and more often. Drop it to 500 and they coast deeper into staleness first. Higher beta means fresher pages and more backend load; lower beta means staler pages and a backend that gets to nap. That’s the entire tradeoff.

Single-flight: who actually does the work

The dice decide whether a refresh should start. They don’t decide who, because under a real burst several readers win the dice in the same instant, and if all of them refreshed you’d have reinvented the stampede. So there’s a hard lock. The first reader to claim the refresh takes a single-flight lock (cache_turbo_lock_ttl sets how long it’s held), and everyone else who rolled a winner just serves stale. One refresh per cycle, full stop. If the refreshing request dies or the backend hangs, the lock expires on its own and the next reader tries. No deadlock, no stuck entry haunting you for a week.

The same lock guards the cold miss too, not just refreshes. With cache_turbo_lock on (the default) the first request for an uncached key goes to the origin and the rest wait for it to fill the slot, instead of all stampeding a page that simply isn’t there yet; cache_turbo_lock_timeout caps how long a waiter waits before giving up and going itself. So both ends of a page’s life, the cold birth and every stale refresh, collapse to roughly one origin request.

The SWR math here was lifted, deliberately, from the same algorithm our WordPress object-cache work uses. Same constants, same dice. Edge cache and object cache speak one language and tune the same way. That was not an accident.

Redirects, negative caching, and “cache forever”

By default cache-turbo stores a 200 OK to a GET (never a HEAD, which would store an empty body, and never a mutating POST/PUT/DELETE). But you can give other status codes a TTL of their own and cache those too:

cache_turbo_valid 30s;              # the default / 200 TTL
cache_turbo_valid 301 302 308 1h;   # cache redirects
cache_turbo_valid 404 410 1m;       # negative caching
cache_turbo_valid 0;                # "cache forever" until purged

Negative caching matters more than it sounds: a flood of requests for a missing URL can hammer your backend just as hard as a popular one, and a 1-minute cache on a 404 turns that into one origin hit a minute. A TIME of 0 means the copy stays fresh indefinitely and is only updated when you purge it. One sharp edge: cache_turbo_valid replaces, it doesn’t merge, so if a nested location sets any cache_turbo_valid of its own it discards the whole inherited set, redirect and 404 lines included. Re-state every status line you still want in the child block.

There’s also a freebie you never configure: conditional requests. If the origin gave the cached 200 an ETag or Last-Modified, cache-turbo answers an If-None-Match or If-Modified-Since with a bodyless 304 Not Modified straight from cache, no origin round trip, when the client’s copy is still current. It only does this from a fresh entry, never a stale one, because a stale copy hasn’t been revalidated and can’t honestly claim “still current.”

And when php-fpm falls over: stale-if-error

Here’s the failure mode that earns this cache its keep. Your PHP-FPM pool maxes out, or a deploy briefly returns 502, or the database has a bad thirty seconds. What do your visitors see? With a plain cache: the error, in full colour. With cache-turbo: nothing, if it can help it.

The everyday case is already covered for free by the stale-while-revalidate you set up in Step 3. When a page is past its TTL but still inside its stale window, the visitor is served the old copy instantly while one background request goes to refresh it. If that background request comes back 500/502/503/504 or simply times out, cache-turbo shrugs and leaves the good copy exactly where it was — the failed refresh never overwrites it, and the visitor never sees the error. The backend gets to fall over in private. That’s stale-if-error, and you don’t type anything to get it.

For outages longer than the stale window, let the origin ask for more grace. If your app (or the nginx in front of it) sends Cache-Control: stale-if-error=600 on a page, cache-turbo will keep serving that stale copy through up to ten minutes of origin 5xxs, marking the served response X-Cache: STALE-IF-ERROR so you can see exactly when it kicked in (it shows up as STALE in $cache_turbo_status too). A ten-minute backend outage becomes a non-event for every page that was warm when it started.

One honest limit, because a cache is not a magician: it can only shield pages it already has a copy of. A page nobody had requested yet, hit for the first time during the outage, has nothing cached to fall back to, so that visitor still gets the error. Caching can’t invent a page it never saw. Which is the best argument there is for cache warming (Step 7’s ?url= verb): a warm cache is also your outage insurance.

Step 4: the cache key is already clean (here’s how to tune it)

A cache key is the string that decides whether two requests are “the same page.” Get it wrong in one direction and you cache too little (every URL looks unique, hit rate is garbage). Wrong the other way and two different pages collide, and people get served each other’s content. This is the part people historically got wrong, so cache-turbo now ships a sane key by default: $host$uri$cache_turbo_normalized_args. Host plus path plus normalized args. You get the right behaviour without typing anything.

What “normalized” buys you for free: it sorts the args (so ?b=2&a=1 and ?a=1&b=2 hit one slot) and drops a built-in denylist of tracking junk: utm_*, fbclid, gclid, msclkid, mc_eid, _ga, ref, plus sid, sessionid and tmp_*. Marketing slaps ?utm_source=twitter on every link, and a dumb cache would treat /post-42?utm_source=twitter and /post-42?utm_source=facebook as two different pages that render identically, caching the same HTML a dozen times while your hit rate quietly bleeds out. cache-turbo collapses them onto one slot out of the box. Add your own params to drop, or nuke them all:

cache_turbo_normalize_strip     sid sessionid "tmp_*";   # extra args to drop (trailing * = prefix)
cache_turbo_normalize_strip     *;                       # or: a bare * matches every arg = drop all

Then the opposite problem: variants that genuinely differ and must not share a slot. The cache keys on the request, not on the response’s Vary header, so if your page differs by gzip-vs-brotli or mobile-vs-desktop and you don’t say so, the first variant stored wins for everyone. You have two ways to fix it. If you know the axes up front, declare them with a vary bucket:

cache_turbo_normalize_vary encoding device;   # keep gzip ≠ brotli, mobile ≠ desktop

The encoding bucket splits by Accept-Encoding class and ranks zstd above brotli (we ship the zstd module, so a zstd-capable client gets its own slot); device splits mobile from desktop by sniffing the User-Agent. Or, if you’d rather learn the axes from the response, turn on auto-Vary:

cache_turbo_auto_vary on;   # read the response's own Vary and split automatically

That reads the response’s own Vary header and splits the cache by the named request header, honouring a safe whitelist (Accept-Encoding, User-Agent device class, Accept-Language, Origin). Anything it can’t safely key on (Vary: *, Cookie, Authorization, or any header off the whitelist) is treated as uncacheable rather than stored under a key that ignores the varied axis. Pick one mechanism per axis: declaring an axis with normalize_vary and letting auto_vary learn it splits the cache on it twice for no benefit. Add only the axes your page actually varies on; an extra one halves your hit rate for nothing.

One safety move for origins you don’t fully trust: if the normalizer might merge two genuinely-private URLs that differ only by a sessionid the origin forgot to mark private, set an explicit raw key and skip the stripping and sorting entirely — cache_turbo_key $scheme$host$request_uri;. Every distinct query then gets its own slot. Belt-and-braces for an upstream that’s careless about per-user marking; the normalized default is fine if your origin is well-behaved.

Step 5: pick a preset, or let it tune itself

Four knobs (valid, beta, lock_ttl, stale window) is three more than most people want to think about on a Tuesday. So pick a vibe:

cache_turbo        ct;
cache_turbo_preset aggressive;

The stale window works out to valid × (multiplier − 1). Balanced plus a 60-second valid means fresh for 60s, served stale for another 180s, then expired. Any explicit knob still beats the preset, so cache_turbo_preset balanced followed by cache_turbo_valid 120s does exactly what you’d hope.

Microcaching: the micro preset for APIs and PHP-FPM

That first column, micro, is the one people sleep on, and it’s quietly the best trick in the box. Microcaching means a deliberately tiny TTL, about a second, on endpoints you’d normally call “too dynamic to cache.” The page is fresh for only one second, so the data is near-real-time, but during that second a burst of N requests is served from RAM and the backend is hit once. On a hammered /api or a PHP app, backend load drops from “every request” to “roughly one per endpoint per second,” and the content is at most a second or two stale. Nobody notices the staleness; everybody notices the server not falling over.

Because cache-turbo runs in the ACCESS phase and captures the body in a filter, it’s upstream-agnostic: the exact same directives microcache a proxy_pass JSON API and a fastcgi_pass PHP-FPM app. And since only GET is cached, mutations sail straight through untouched. For a CMS there’s a shortcut that auto-skips the admin, login and logged-in-cookie surfaces for you:

location ~ \.php$ {
    cache_turbo               ct;
    cache_turbo_preset        micro;          # valid 1s + lock_ttl 1s + ×2 stale, in one word
    cache_turbo_lock          on;             # collapse the per-second burst to ONE origin hit
    cache_turbo_backend       wordpress;      # auto-skip wp-admin, login + logged-in cookies
    cache_turbo_cache_control respect;        # pin the 1s TTL regardless of app headers
    cache_turbo_no_store      $cookie_PHPSESSID;

    include      fastcgi_params;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

The cache_turbo_backend directive takes generic (a.k.a. auto), wordpress, woocommerce or joomla, and a request that looks like a session (login cookie, admin URI, dynamic arg) skips the cache entirely. One catch worth knowing: enabling any CMS preset defaults cache_turbo_cache_control to honor, so an app emitting Cache-Control: max-age=600 would override your 1s unless you pin it back with cache_turbo_cache_control respect, as above. For the per-user safety net, cache_turbo_bypass and cache_turbo_no_store let you name a session cookie so a logged-in GET is never collapsed onto the anonymous slot.

Autotune: let it read the load

If you genuinely can’t be bothered to pick numbers, turn on autotune:

cache_turbo_autotune on;

This one grew up since the early builds. It measures how long your backend actually takes to regenerate a page, and when the origin is genuinely under load it dials three things: it picks beta from the measured cost (clamped to your preset’s band), it widens the serve-stale window so a stale entry stays serveable longer before becoming a hard miss, and it widens the single-flight lock_ttl so a slow regen isn’t re-claimed mid-flight. All three are bounded at four times their configured value, and the load factor it’s using is published per-zone as cache_turbo_autotuned_load (1000 = baseline, up to 4000). The instant your backend is no longer struggling, it snaps everything back. So a traffic spike transparently buys the cache more headroom and tighter dogpile control, and it all reverts on its own once the spike passes.

The one thing autotune will never touch is the fresh TTL. A client is never told “fresh” about content older than your cache_turbo_valid contract; only the best-effort stale grace and the dogpile window stretch. It recomputes every 30s off the live shared-memory stats. Watch it work by exposing $cache_turbo_beta as a header and watching the number drift as your backend’s mood changes. Closest this module gets to a party trick.

What an nginx page cache should and shouldn’t store

Before you go to production, know the safety rails, because a cache that serves the wrong person’s page is not a performance feature, it’s a data breach with good latency. cache-turbo only stores a 200 OK to a GET, and it flatly refuses anything that looks per-user: a request carrying an Authorization header (which is also never served a cached copy, so an anonymously-primed page never leaks to a credentialed caller), a response that sets a cookie (Set-Cookie), or a response marked Cache-Control: private, no-store, no-cache, max-age=0, or s-maxage=0. It also honours request Cache-Control: no-cache forces a revalidation, no-store runs the request without storing, and only-if-cached answers 504 rather than touch the origin. Those signals mean a page belongs to one specific human. Someone caches a page with a logged-in username in the corner, and suddenly every visitor is “Hi, Dave.” The defaults exist so you have to go out of your way to make that mistake. Don’t go out of your way.

Step 6: add a shared L2 for a fleet

One nginx box is happy on L1 alone. The moment you have several, you want them to share a cache so one box warming a page warms everybody, and a rebooted box refills from the shared tier instead of stampeding the origin like a cold herd. That’s L2. One line:

# plain, same box
cache_turbo_redis redis://127.0.0.1:6379/0;

# ACL user, password, db 2, remote
cache_turbo_redis redis://cache:s3cret@10.0.0.5:6379/2;

# TLS, verifying the server cert against the system CA by default
cache_turbo_redis rediss://redis.internal:6380/0;

# TLS with a private CA and an overridden verified name
cache_turbo_redis rediss://10.0.0.5:6380/0 tls_ca=/etc/ssl/redis-ca.pem tls_name=redis.internal;

The contract that keeps it fast: write-through on store, one GET on an L1 miss, and it never touches Redis on an L1 hit. The hot path stays in local RAM; Redis only catches the misses. rediss:// (two s’s) means TLS, verification is on by default (the correct default, leave it alone unless you can say out loud why you’re turning it off), and the password sits in your nginx config so chmod 600 it and keep it out of git, same as every secret you’ve been tempted to commit at 2 a.m. and regretted. There’s a keepalive=N option to pool idle connections per worker if you want to skip the per-op reconnect. If you want a hardened Redis to point it at, our Valkey package is the obvious backend. (And if you’re wondering why compressing secret-adjacent responses is its own footgun, the BREACH attack is the cautionary tale.)

Already running memcached instead of Redis? Point the L2 there with cache_turbo_memcached 127.0.0.1:11211 prefix=mc:; — same write-through-on-store, sync-GET-on-miss model, native client, no libmemcached. It’s the deliberately lean option: memcached has no sorted sets, no SCAN and no atomic SET-NX, so it can’t do tag purges, whole-keyspace purges or the cross-node single-flight lock (per-box single-flight still works), and values over its 1 MiB ceiling stay L1-only. Use Redis if you need tags or cluster-wide dogpile protection; reach for memcached if you already run one and just want a simple shared object tier. The two are mutually exclusive in the same block.

Step 7: wire up the admin endpoint, and lock it down

You get a built-in control panel: stats, purging, and cache warming. Point a location at the zone, and optionally let it answer the PURGE method too:

location = /_cache {
    cache_turbo_admin ct;
    cache_turbo_purge on;        # also accept PURGE <uri>
    allow 127.0.0.1;
    deny  all;
}

Curl it for JSON stats, and purge in three flavours: one page, everything sharing a tag, or the whole zone. With cache_turbo_purge on you can also drop a single URL with a PURGE request to it directly, which beats reconstructing the cache key by hand:

$ curl localhost/_cache
{"hits":1240,"misses":83,"stale_serves":12,"refreshes":11,"evictions":0,"l2_hits":61,"l2_misses":22,"cost_ms":34,"autotuned_beta":1700,"autotuned_load":1000}

$ curl -X POST  'localhost/_cache?key=example.com/blog/post-42'  # one entry (verbatim key)
$ curl -X PURGE 'localhost/blog/post-42'                         # ...or just PURGE the URL
$ curl -X POST  'localhost/_cache?tag=post-42'                   # everything tagged
$ curl -X POST  'localhost/_cache?all=1'                         # the nuclear option
$ curl -X POST  'localhost/_cache?url=/,/blog/,/about'           # warm cold pages

Tag purging is the good stuff. Set cache_turbo_tag from a response header (your backend emits something like X-Cache-Tags: post-42 author-dave category-nginx) and you can invalidate every page touched by one author or one category in a single call. It needs Redis on, because the tag index lives in its sorted sets. This is the difference between “I edited a post” and “I have to flush everything and re-warm forty thousand pages.” One footnote on ?key=: it hashes the string verbatim, so it has to equal the entry’s full cache-key value (for the default key that’s <host><uri><normalized-args>, e.g. example.com/blog/post-42), not just the path. The PURGE method exists precisely so you don’t have to think about that.

Now the part where I get loud, and it’s the one line of this whole guide I’ll state without a hedge. That allow/deny is not optional. The endpoint purges your cache and fires server-side fetches to local paths. Left public, ?all=1 is a denial-of-service button with a friendly URL, and ?url= pointed at the wrong place is a server-side request forgery primitive someone finds with a scanner inside a week. An admin endpoint with no gate isn’t a convenience, it’s an incident waiting for a CVE number.

Step 8: scrape it with Prometheus

The same endpoint speaks Prometheus. Add ?format=prometheus and point a scrape at it, every sample labelled by zone so one job watches many zones:

$ curl 'localhost/_cache?format=prometheus'
cache_turbo_hits_total{zone="ct"} 1240
cache_turbo_misses_total{zone="ct"} 83
cache_turbo_stale_serves_total{zone="ct"} 12
cache_turbo_refreshes_total{zone="ct"} 11
cache_turbo_evictions_total{zone="ct"} 0
cache_turbo_l2_hits_total{zone="ct"} 61
cache_turbo_l2_misses_total{zone="ct"} 22
cache_turbo_lock_waits_total{zone="ct"} 9
cache_turbo_min_uses_skips_total{zone="ct"} 4
cache_turbo_bypasses_total{zone="ct"} 5
cache_turbo_regen_cost_ms{zone="ct"} 34
cache_turbo_autotuned_beta{zone="ct"} 1700
cache_turbo_autotuned_load{zone="ct"} 1000

The number you’ll stare at is hit ratio: rate(cache_turbo_hits_total[5m]) / (rate(cache_turbo_hits_total[5m]) + rate(cache_turbo_misses_total[5m])). At 0.98 your backend is asleep and you’re winning. At 0.40 something’s wrong with your key, probably a Vary axis you forgot to split back in Step 4. Watch cache_turbo_evictions_total too: if it’s climbing, the zone from Step 2 is too small and the LRU is throwing out pages you wanted. The l2_hits/l2_misses pair tells you how much work Redis is saving the origin, bypasses_total isolates the requests you skipped to origin on purpose (a cache_turbo_bypass predicate or a CMS preset) from genuine misses, and autotuned_load climbing toward 4000 is your live “the backend is under pressure right now” gauge. There’s a ready-made Grafana dashboard shipped in tools/grafana-dashboard.json: import it, pick your Prometheus datasource, and you get hit ratios, L1/L2 request rates, regen cost and autotuned beta with a per-zone template variable. And gate the scrape behind the same allow/deny; your metrics are nobody else’s business.

Step 9: verify it actually works

Reload nginx (nginx -t first, always, because the missing semicolon you can’t see will take the site down on reload), then curl the URL twice and grep for the header:

$ curl -sI localhost/ | grep -i x-cache      # 1st: nothing, it was a miss
$ curl -sI localhost/ | grep -i x-cache
X-Cache: HIT                                  # 2nd: served from RAM

That header is your whole debugging story. HIT means fresh from cache. STALE means an old copy while a refresh runs in the background. No header at all means it went to the backend. When someone swears the cache “isn’t working,” this settles the argument in one curl. (If you’d rather not advertise cache state to the public, strip the X-Cache header downstream with the standard nginx header tooling; the RFC-meaningful Age still goes out.) For logs rather than curl, drop $cache_turbo_status into a log_format — it records HIT, STALE, MISS, BYPASS (a cache_turbo_bypass or CMS-preset skip) or EXPIRED per request, so you can chart cache outcomes straight from the access log.

Optional: stack it over nginx’s disk cache

Remember L1 holds your hot set, not the whole site? Here’s where that resolves. You can run cache-turbo and nginx’s built-in proxy_cache together, because they sit at different layers. cache-turbo runs in the ACCESS phase in shared memory; proxy_cache runs later, in the content phase, on disk. On a cache-turbo hit the request finalizes before it ever reaches proxy_pass, so the disk cache never runs. On a miss it flows through proxy_cache as usual and cache-turbo captures whatever comes back into shm. So cache-turbo becomes an L0 over the disk L1:

location / {
    cache_turbo       ct;
    cache_turbo_valid 30s;
    proxy_cache       disk;
    proxy_cache_valid 200 10m;
    proxy_pass        http://app;
}

Two things bite if you stack carelessly. The caches store and purge independently (same page can live in shm and on disk, and purging one ignores the other), so keep the disk TTL at or above the shm TTL. And cache-turbo strips the disk cache’s Age, X-Cache and X-Cache-Status before storing, so an L1 hit never replays a frozen age; cache-turbo’s own X-Cache is the source of truth, read $upstream_cache_status for the disk layer’s opinion. Rule of thumb: don’t double-cache the same content. shm for hot HTML that benefits from SWR, Redis and tag purge; disk for a huge corpus that won’t fit in RAM.

So how fast is it, really?

Numbers, because “it’s fast, trust me” is what every README says. The repo ships a benchmark harness (tools/bench.sh) that stands up one nginx with four edges sharing the same origin and payloads — no cache at all, nginx’s own proxy_cache, cache-turbo in RAM, and cache-turbo with a Redis tier — primes each so it’s actually serving from cache, then hammers it with wrk and checks the hit ratio is genuinely 100% before believing a single number. Here’s a stock-nginx build serving cached pages, requests per second (higher is better):

payload     no cache     proxy_cache   cache-turbo (RAM)
tiny 200B   23,000       493,000       605,000   (+23% over proxy_cache)
med  200KB  14,700        41,400        56,800   (+37%)
large 4MB    1,000         2,510         2,750   (+10%)

Two separate wins hide in that table. First, caching at all is the giant one: on a small page, 23k requests/sec without a cache becomes 600k with one, because a hit skips the entire backend round-trip. That’s the 20-to-25× that makes this whole exercise worth it, and you get it from proxy_cache too. Second, cache-turbo beats nginx’s own disk cache by 23–37% on small and medium pages, with lower median and tail latency, because a shared-memory hit never touches the disk. The edge shrinks to ~10% on a 4MB body — at that size the wall-clock is dominated by copying four megabytes out the socket, which every contender pays equally, so the cache machinery stops being the bottleneck. The Redis tier serves at the same speed as plain RAM, by design: an L1 hit never calls Redis, so the L2 only earns its keep when a different box needs the page.

Fair-play caveat, because benchmarks lie by omission: these are loopback, single-box, best-case (100% hit, one hot key) numbers. Treat the gaps between the columns as the real signal, not the absolute rps — your network, TLS and traffic mix will move every number, but the shape holds. Run tools/bench.sh on your own box if you want your own truth; that’s what it’s there for.

cache-turbo vs proxy_cache: when to pick which

Speed isn’t the whole story, and nginx’s built-in proxy_cache is a fine, battle-tested cache. Here’s the honest split.

Where cache-turbo wins:

• It’s faster, and it serves in the access phase from RAM, so it can sit as an L0 in front of proxy_cache rather than replace it.
• Stale-while-revalidate and stale-if-error are built in and on by default — the resilience from the last two sections. proxy_cache can serve stale, but only after you wrestle proxy_cache_use_stale and friends into shape.
• Dogpile protection that crosses machines. proxy_cache_lock collapses a stampede per box; cache-turbo’s single-flight also coordinates a whole fleet through the Redis lock.
• A shared L2. A cluster of nginx boxes share one Redis/memcached cache, so one box warming a page warms them all. proxy_cache is per-box disk, every node cold on its own.
• One cache for every upstream. The same directives microcache a fastcgi_pass PHP-FPM app and a proxy_pass API — stock nginx makes you run fastcgi_cache and proxy_cache as two separate systems with two separate configs. (Caching dynamic and PHP-FPM responses isn’t the win here — nginx does that fine — the unified config and the single-flight that makes a 1-second TTL safe is.)
• Operational extras: tag-based purging, auto-Vary, CMS auto-classify, and a JSON + Prometheus admin endpoint baked in.

Where proxy_cache still wins:

• It’s already in nginx. Nothing to compile or package; cache-turbo is a third-party module you build or install (prebuilt here, but still a moving part).
• Its cache is on disk, so it survives a reload or restart and holds far more than fits in RAM. cache-turbo’s L1 is shared memory, cleared on every reload — the Redis L2 softens that, but it’s another service to run.
• A huge cold corpus — big media, a long-tail archive — belongs on disk. Don’t pin gigabytes of rarely-touched files in shared memory.
• Maturity. proxy_cache has a decade of every weird edge case shaken out of it.

Short version: hot HTML and dynamic apps lean cache-turbo; a giant on-disk archive leans proxy_cache; and when in doubt, stack them — cache-turbo for the hot set in RAM, proxy_cache as the deep disk tier behind it.

Related reading

• Valkey explained: the Redis fork that actually won: the L2 tier’s natural backend, and why we package it hardened.
• What is zstd? nginx, Angie, history and browser support: the encoding the Step 4 vary bucket ranks above brotli.
• What is the BREACH attack?: why compressing secret-adjacent responses is its own footgun.
• Database Boost: the other end of the slow-backend problem, on the database side.

One last thing, because it’s the mistake everyone makes once. Before you ship cache_turbo_preset aggressive to production, set a short cache_turbo_valid and watch your X-Cache headers and eviction counter for an afternoon. The cache that serves stale content for five minutes because you fat-fingered a TTL is the cache that gets blamed for a bug that doesn’t exist. Ask me how I know.

That gap is exactly what the nginx-error-abuse-module closes. It’s a dynamic NGINX module, written in C, that watches the status codes your server hands back and temporarily blocks any client generating too many errors. A hundred errors in five minutes? Gone for an hour. Think fail2ban, except it lives inside the worker process instead of tailing a log file from the outside, and it makes its decision before the next request ever reaches your application.

Source is on GitHub: github.com/eilandert/nginx-error-abuse-module. No Lua, no njs, no sidecar daemon. Let’s get into what it does, why you’d want it, and the three or four places it’ll bite you if you’re careless.

What the error-abuse module actually does

Here’s the whole idea in one sentence: you tell it which status codes count as abuse, how many a client gets in a time window, and how long to lock them out when they cross the line.

A client trips the threshold, and from that point every request gets a 429 Too Many Requests (or whatever status you pick) until the block expires. The client’s own blocked requests don’t count against them, so a banned bot hammering your door doesn’t extend its own sentence. That detail matters more than it sounds. Get it wrong and an aggressive scraper renews its ban forever, which is either a feature or a footgun depending on how much you enjoy clients that can never recover.

The codes you watch are yours to choose. A list, a range, or both: 403,404,429,500-599 is a perfectly normal config. Watching the 5xx range is the interesting one, because a flood of 500s usually means somebody found the one URL that makes your backend cry, and you’d rather not let them keep poking it while you figure out why.

Counting happens in an NGINX shared-memory zone, so every worker sees the same tally. The bot doesn’t get its allowance per worker. It gets one budget, total, across the whole server. And because the module sits in the response phase, the cost for normal traffic is close to nothing. A 200 response barely touches it. It only does real work when something actually errored.

Why not just fail2ban or limit_req?

Fair question. You’ve probably got both already. Here’s the honest comparison, scars included.

Fail2ban works by reading your logs. Something has to write the log line, fail2ban has to read it, parse it with a regex, decide, then shell out to iptables or nftables to install a rule. That whole pipeline has latency measured in seconds, and it depends on a second process staying alive, your log format not drifting, and the regex still matching after the next NGINX upgrade quietly renames a field. I’ve watched fail2ban silently stop banning anything for three weeks because a log format tweak broke one capture group. Nobody noticed until the bill from the bandwidth showed up.

The error-abuse module makes the decision in-process, in microseconds, with no log round-trip and no firewall syscall. The state lives in shared memory the worker already has mapped. There’s no second daemon to babysit.

And limit_req? Great tool, wrong job. It throttles request rate, full stop. It doesn’t know or care whether those requests succeeded. A client politely fetching your sitemap at 10 req/s looks identical, to limit_req, to a client brute-forcing logins at 10 req/s. The error-abuse module only cares about the ones that failed. That’s the distinction: limit_req rations everyone, error-abuse punishes the clients that are obviously up to no good and leaves your legitimate fast traffic alone.

Use all three. They don’t overlap. limit_req caps the firehose, the error-abuse module catches the error-storming scanners, and fail2ban can still mop up at the network layer for the stuff that never reaches NGINX at all. If you’re already running a WAF, this pairs nicely with it too. See our guide on installing ModSecurity and the OWASP CRS on NGINX for the layer that inspects request content rather than counting failures.

The five-minute config

Load the module, declare a Redis endpoint if you want one (optional, skip it for now), declare a zone, then switch it on in a location. Here’s a working setup with every knob labelled.

load_module modules/ngx_http_error_abuse_module.so;

http {
    error_abuse_zone zone=client_errors:10m
                     key=$binary_remote_addr
                     statuses=403,404,500-599
                     interval=300s
                     threshold=100
                     block=60m
                     inactive=1h;

    log_format main '$remote_addr "$request" $status '
                    'error_abuse=$error_abuse_status '
                    'count=$error_abuse_count';

    server {
        location / {
            error_abuse zone=client_errors status=429;
        }
    }
}

Read it out loud and it explains itself. A client identified by IP ($binary_remote_addr) gets threshold=100 matching errors inside a rolling interval=300s (five minutes) before it earns a block=60m timeout. The 10m after the zone name is the shared-memory size, not a duration, which trips up everyone exactly once. The inactive=1h tells the module to forget about a key after an hour of silence so the zone doesn’t fill up with one-time visitors.

nginx -t before you reload. Always. The one time you skip it is the time you fat-fingered the zone size and took the vhost down on a Friday afternoon.

The sliding window, and why it matters

Most naive rate limiters use a fixed window. Reset the counter every ten seconds on the clock, count until it resets. The problem is the boundary. A client can fire five requests in the last half-second of one window and five more in the first half-second of the next, and slip ten requests through a “five per ten seconds” rule without ever tripping it. Attackers know this. It has a name, the fixed-window boundary problem, and it’s exactly the kind of thing a determined scanner probes for.

The error-abuse module uses an exact sliding window instead. The interval moves with the client. Every request looks back across the real previous interval seconds, not at an arbitrary clock-aligned bucket. There’s no seam to exploit. It costs a little more bookkeeping per key, which is why threshold is capped at 1024: the per-key memory stays bounded no matter how clever you get with the numbers.

One thing to internalise. The window, the threshold, and the block are independent. interval is how far back it looks. threshold is how many errors fit in that look-back before the hammer drops. block is how long the hammer stays down, and it has nothing to do with the interval. You can watch a tight 10-second window but block for a full day. Tune them separately to taste.

Picking the key: IP, account, or something smarter

By default you key on the client IP, and for most setups that’s the right answer. But the key is just an NGINX variable, which means it can be anything the request gives you. An authenticated API? Key on the account ID and a single abusive user can’t dodge the ban by bouncing across a /16 of cloud IPs. A tenant identifier, a session token, a hash of something. Your call.

Now the part that pages people. If you run behind a CDN or a load balancer, every request arrives wearing the proxy’s IP, not the client’s. Key on $binary_remote_addr naively in that setup and you’ll either ban your own load balancer (taking out everyone at once) or never ban anyone, because all the traffic shares one address. Neither is the outcome you wanted.

The fix is the standard ngx_http_realip_module, configured to trust only your actual proxies:

set_real_ip_from 10.0.0.0/8;
set_real_ip_from 2001:db8::/32;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

error_abuse_zone zone=client:10m
                 key=$binary_remote_addr
                 statuses=404 interval=30s threshold=10 block=15m;

With realip set up correctly, $binary_remote_addr resolves to the genuine client again and everything works. What you must never do is reach for the raw X-Forwarded-For header as your key without realip in front of it. That header is client-supplied. An attacker just sticks a fresh fake IP in it on every request and your ban list fills with ghosts while the real bot strolls through. Trust the header only from sources you control.

For allowlists, there’s an elegant trick: the module ignores empty keys entirely. So a map that returns an empty string for the addresses you trust skips them with zero overhead, no special directive needed.

map $remote_addr $error_abuse_key {
    127.0.0.1   "";
    10.0.0.0/8  "";
    default     $binary_remote_addr;
}

error_abuse_zone zone=external:10m
                 key=$error_abuse_key
                 statuses=403,404 interval=30s threshold=10 block=15m;

Localhost and your internal range now sail past untouched. Health checks from your monitoring stop accidentally banning themselves. Everyone else gets counted.

Surviving a restart: disk persistence

Out of the box, counters live in shared memory and survive a graceful reload (nginx -s reload) automatically. The module hands state across to the new workers. Good.

What a graceful reload does not cover is a full stop and start, or a host reboot, or the OOM killer waking up and shooting a worker in the head. Shared memory evaporates, and every ban resets to zero. The bot you locked out two minutes ago gets a clean slate the moment systemd restarts the service after your kernel upgrade.

Add persist= and the module snapshots state to disk:

error_abuse_zone zone=client_errors:10m
                 key=$binary_remote_addr
                 statuses=403,404,500-599
                 interval=300s threshold=100 block=60m
                 persist=/var/lib/nginx/error-abuse-client_errors.state
                 persist_interval=5s;

The state directory has to exist and be writable by the worker user before NGINX starts. The module won’t create it for you, and it won’t be subtle about complaining. Each persistent zone needs its own file. The snapshot writes atomically every persist_interval (5 seconds by default), so a crash loses at most a few seconds of counting. Graceful shutdown writes one final snapshot on the way out.

Every snapshot carries a CRC32 checksum. If the file is corrupt, half-written from a power cut, or scribbled on by a bad disk, the module spots the bad checksum, deletes the file, logs the error, and starts clean rather than loading garbage state. The format is versioned, binary, and deliberately local. It is not a sync mechanism between hosts, just one server’s memory of who it was annoyed at. For sharing bans across machines, you want the next section.

Redis: one ban list for your whole fleet

Run more than one NGINX box behind a balancer and you’ve got a coordination problem. A scanner trips the threshold on node A, gets banned there, and the load balancer cheerfully sends its next request to node B, which has never heard of it and starts counting from zero. The attacker effectively multiplies their allowance by your number of front-ends. Embarrassing.

Point the module at a shared Redis and the ban becomes fleet-wide:

http {
    error_abuse_redis host=127.0.0.1 port=6379
                      prefix=ea_ timeout=100ms;

    error_abuse_zone zone=client_errors:10m
                     key=$binary_remote_addr
                     statuses=403,404,500-599
                     interval=300s threshold=100 block=60m
                     redis=on;
}

Every host using the same prefix and the same zone settings now shares one counter. Ban on node A, banned everywhere, instantly. The I/O is asynchronous: block lookups pause that one request’s processing without blocking the worker, and matching responses queue an atomic sliding-window update. Each worker holds a single Redis connection, not one per request. It speaks plain RESP, so a Valkey server works exactly the same as Redis. The default key prefix is ea_, and every host in a zone has to agree on it.

Locking down the Redis link: TLS, AUTH, and a separate DB

That shared Redis is also a shared liability, which is the next section’s whole point, so the module gives you the three knobs you actually need to harden the link. You don’t have to settle for a plaintext connection to an open port and hope nobody’s listening.

error_abuse_redis host=tls://redis.internal port=6380
                  user=erroruser password=secret
                  db=3 prefix=ea_ timeout=100ms;

Three things changed there, each optional. The tls:// prefix on the host (or rediss://, same thing) wraps the connection in TLS, with the server certificate verified against the system CA store at /etc/ssl/certs and checked against the hostname. That needs libhiredis_ssl at build and run time, and note one current limitation: a self-signed server cert won’t pass, because there’s no cacert= override yet. The user= and password= pair does Redis 6+ ACL authentication (a bare password= on its own sends a legacy AUTH); leave both off and it connects unauthenticated, same as before. And db=3 issues a SELECT so the module’s keys live in their own logical database instead of squatting in DB 0 next to whatever else you cache there.

The critical design choice here is what happens when Redis falls over. Because Redis always falls over eventually, usually during the incident you can least afford it. The module is fail-open. Redis unreachable means the local shared-memory zone keeps right on enforcing its own counters. You lose the cross-host coordination, you don’t lose protection, and you definitely don’t take an outage on your web tier because a cache node hiccuped.

It goes one better with a circuit breaker. After five consecutive Redis failures the module stops trying for thirty seconds, then tests the water again. Without that, every single request would keep flogging a dead Redis, filling your error log with thousands of identical timeout lines and burning syscalls on a connection that isn’t coming back. The breaker means one terse log line instead of a denial-of-service against your own logging. Anyone who’s watched a log partition fill to 100% during an outage, then watched the outage get worse because the disk filled, knows precisely why this matters.

One honest caveat, and the README is upfront about it: when redis=on, your Redis server becomes a trust boundary. A compromised Redis could inject fake bans or fiddle the counters. So keep it on a trusted network, firewall it, turn on the tls:// transport and the user=/password= ACL from the section above, and don’t expose it to the same internet you’re trying to defend against. If you’re hardening the box it runs on, our Docker hardening guide covers locking down the surrounding container.

Operating it without breaking prod

Never deploy a blocking rule straight to live traffic. You will get the threshold wrong on the first try, lock out something legitimate, and learn about it from an angry customer instead of a graph. So the module ships a dry-run mode.

location / {
    error_abuse zone=client_errors dry_run=on log_level=warn;
}

In dry-run the module does all its counting and decision-making and logs exactly who it would have blocked, while letting every request through untouched. Run it for a day. Read the logs. Find out that your threshold of 5 would have banned the Googlebot crawling a section of stale 404s, raise it, and only then flip dry-run off. This is the difference between a tool that protects you and a tool that becomes the outage.

It exposes three log variables so you can actually see what it’s doing:

• $error_abuse_status resolves to BYPASSED, PASSED, COUNTED, BLOCKED, or DRY_RUN. One word that tells you the decision for this request.
• $error_abuse_count is how many matching errors are currently sitting in this client’s sliding window. Watch it climb.
• $error_abuse_blocked_until is the Unix timestamp the block lifts, or 0 if the client is clean.

Put them in your log_format and your access log becomes a live feed of the module’s reasoning. Grep for BLOCKED to see who’s currently in the penalty box. Grep for DRY_RUN during a trial run to size your threshold before it’s load-bearing.

A couple of operational truths worth tattooing somewhere. Shared-memory exhaustion is fail-open: if the zone fills, the request is served and an error logged, never dropped. A zone’s key and threshold can’t change across a graceful reload, so when you need to change either, declare a new zone name instead of editing the old one in place. And subrequests don’t count, nor do responses the module itself generates, which is what stops a banned client from extending its own ban into eternity.

Building and installing it

It’s a standard dynamic module. You need libhiredis for the Redis support, even if you never turn Redis on, because it links at build time regardless.

apt-get install libhiredis-dev

./configure --with-compat \
    --add-dynamic-module=/path/to/nginx-error-abuse-module
make modules

The --with-compat flag is what lets the resulting .so load into a binary-compatible NGINX you didn’t compile yourself, which is almost certainly the one your distro shipped. Drop objs/ngx_http_error_abuse_module.so into your modules directory, add the load_module line, and you’re off.

If compiling modules by hand isn’t your idea of a good evening, that’s rather the point of this whole site. The module is part of our prebuilt NGINX packages and Docker images, so you can apt install it alongside the rest of the stack instead of wrestling a build tree. Browse the full set on the NGINX modules page. The repo also carries a GitHub Actions matrix that runs the test suite under Valgrind and CodeQL on every push, because a security module that leaks memory or carries its own vulnerabilities is just a different shape of the problem you were trying to solve.

Frequently asked questions

Related reading

• How to Install ModSecurity and OWASP CRS on NGINX — the content-inspecting WAF layer that pairs with error-counting.
• Valkey Explained: The Redis Fork That Actually Won — the cache engine behind cluster-wide bans.
• What Is the BREACH Attack? — another HTTPS-layer threat and how to shut it down.
• NGINX Modules, optimized & extended — the full set of prebuilt modules in our APT repo.

Anyway. Set dry_run=on first, watch the logs for a day, and only then let it start swinging. The bot that’s been hammering your 404s since last Tuesday isn’t going anywhere.

This is the story of rspamd-kam-rules, a small converter that takes Kevin McGrail’s famous SpamAssassin ruleset and turns it into a single native Rspamd Lua plugin. No Perl. No compatibility shim parsing 6,500 lines on every reload. Just 3,248 rules that actually resolve against the symbols your Rspamd already has, with the dead weight stripped out before it ever hits production.

Two spam fighters, one ruleset

SpamAssassin is the elder, and KAM.cf is one of the best community rulesets ever written for it: 3,000-plus patterns hunting phishing, malware droppers, and the endless tide of “RE: your invoice” that turns out to be an XLSM with a macro that wants to be friends with your domain controller. It’s maintained by Kevin A. McGrail with help from Joe Quinn, Karsten Bräckelmann, Bill Cole, and Giovanni Bechis. It’s genuinely good. It’s also written in SpamAssassin’s dialect, which means it expects SpamAssassin to run it.

Rspamd is the younger, faster animal. Event-driven C core, Lua for the logic, and a regexp engine that compiles every pattern once at startup and scans each message in a single pass with Hyperscan. A SpamAssassin box doing KAM.cf might average 800 ms per message under load; the same logic on Rspamd lands closer to 40 ms. That’s the whole reason people want KAM.cf on Rspamd. If you want the full tour of how Rspamd decides what’s spam, I covered that in how modern spam filtering works. This piece is about feeding it KAM.cf without doing something you’ll regret.

The trap: just point Rspamd at the .cf file

Rspamd ships a spamassassin module. Drop your .cf into the config, point the module at it, reload. And it works. Sort of. Here’s the part the tutorials skip.

It parses the entire ruleset on every config load, all 6,500 lines, including the hundreds of rules it can’t run: eval: calls into SpamAssassin plugins Rspamd never implemented, askdns lookups it handles its own way, metas referencing symbols from plugins you don’t have. But the one that pages you later is subtler: symbol names don’t match. SpamAssassin calls a passing SPF check SPF_PASS; Rspamd calls it R_SPF_ALLOW. SpamAssassin says DKIM_VALID; Rspamd says R_DKIM_ALLOW. A KAM.cf meta like (FREEMAIL_FROM && SPF_PASS && BITCOIN_ADDR) references a symbol your Rspamd never raises under that name, so the meta silently never fires. It compiles fine. It costs you CPU at startup. It catches nothing. No error. Just a rule that looks active and is functionally dead, which is the worst kind, because you’ll trust it.

You find out the hard way, of course. A spam wave gets through, you grep the logs, and the rule you were counting on never raised a single hit in three months.

The fix: transpile, don’t interpret

rspamd-kam-rules takes the other road. It reads KAM.cf with a proper parser, works out which rules can genuinely run on your Rspamd, rewrites the SA symbol names to their Rspamd equivalents, throws away everything that can never fire, and emits one self-contained kam.lua. That file is the only thing that touches your Rspamd. It carries a SHA-256 of the exact KAM.cf it came from, and it registers its regexes straight into Rspamd’s native regexp cache.

The current run converts 3,248 rules: 1,179 body, 1,116 header, 690 meta, 156 URI, 67 rawbody, 38 MIME header, and 2 full-message. Another 179 meta rules get dropped on the floor, on purpose, because they depend on symbols that don’t exist on the target. More on that fight in a minute. It’s the most interesting part.

Parsing KAM.cf properly means handling the bits that bite. Conditional blocks: it tracks the ifplugin / if !plugin(...) / else / endif stack and only emits rules whose entire chain is satisfiable, while an unbalanced endif raises an error instead of silently corrupting the set. Regex extraction: SpamAssassin patterns come as /pattern/flags or m{pattern}flags with arbitrary delimiters, so the extractor walks the string tracking escapes rather than naively splitting on a slash that a character class would laugh at. And replace_tag / replace_rules: KAM.cf writes /foo<LETTER>/ and defines <LETTER> once, so the converter resolves those tags to a fixpoint and expands them inline. It also preserves tflags multiple maxhits=N, so a rule that hits five times scores five times, exactly like the original.

The symbol map: speaking Rspamd’s language

Here’s where the converter earns its keep. It carries a translation table from SpamAssassin symbol names to Rspamd native ones: SPF_PASS to R_SPF_ALLOW, DKIM_VALID to R_DKIM_ALLOW, the whole URIBL_* family onto Rspamd’s SURBL and DBL symbols. A meta rule is only as good as the symbols it references. Map SPF_FAIL to R_SPF_FAIL and the meta fires; leave it as SPF_FAIL and it sits there forever, compiled and useless. The map is what turns a pile of inert metas into rules that actually vote.

At runtime the generated Lua keeps that table too. When a meta references a symbol that isn’t a KAM rule itself, the plugin calls task:has_symbol() on the mapped Rspamd name, reading the result your existing modules already computed. The converter isn’t reimplementing SPF. It’s wiring KAM’s logic into the checks Rspamd already runs.

Pruning the dead: meta resolution as a fixpoint

This is the bit I’d put on the whiteboard. A meta depends on other symbols, which might be regex rules, external Rspamd symbols, or other metas that depend on yet more symbols. You can’t judge a meta in isolation. You have to know whether everything it transitively depends on is reachable.

So the converter iterates to a fixpoint. Start with the known-good set: every regex rule that parsed, plus the external Rspamd symbols you fed it. Walk every meta; if all its dependencies are in the good set, mark it good and add it. Repeat until a pass adds nothing. Anything still unresolved depends on a symbol nobody can provide, and out it goes, with its missing dependencies recorded in the report so you can see exactly why. That’s the 179 dropped metas: not bugs, just rules referencing symbols this Rspamd doesn’t have. Shipping them would mean compiling expression trees that can never be true.

You feed the target’s symbol set in via two text files. external-symbols.txt is dumped straight from your production Rspamd’s /symbols endpoint, the real list of everything your instance can raise. unavailable-symbols.txt is the explicit blocklist of KAM symbols you know aren’t registered on your stack. Change stacks, regenerate the dump, rebuild. The output adapts to the box it’s actually going to run on, which is more than the SA module ever does for you.

Why the Lua is fast: register once, scan once

At config load, the plugin registers each pattern with rspamd_config:register_regexp, tagged by type: sabody for body, sarawbody for rawbody, message for full, url for URI, and the header variants for the rest. That tag tells Rspamd which slice of the message the pattern wants to see. Then the regexp cache does its thing: every pattern of a given type gets compiled into one combined Hyperscan database, and a message is scanned once to find every match in a single pass. Compare that to SpamAssassin’s per-rule, per-message Perl loop that pins your cores. Same patterns, completely different cost model. That’s why the converter bothers to register properly instead of calling string.match in a loop like a tutorial would.

Metas compile through rspamd_expression.create into proper expression trees that short-circuit. Results are cached per-task, so a symbol referenced by ten metas is evaluated once. There’s even a recursion guard: the cache entry is set to zero before evaluation starts, so a pathological meta cycle returns zero instead of blowing the Lua stack. Small detail, big difference between a bad rule scoring nothing and a bad rule taking down your scanner.

Installing it, and the auto-update that won’t wake you up

The build runs in GitHub Actions daily at 3 a.m. UTC. It checks the Last-Modified header on KAM.cf and does nothing if upstream hasn’t changed: no rebuild, no commit, no churn. When it has changed, it runs the tests, regenerates kam.lua, and commits the new file with its fresh SHA-256. Deploying is three boring lines:

sudo wget -O /etc/rspamd/plugins.d/kam.lua \
  https://raw.githubusercontent.com/eilandert/rspamd-kam-rules/main/dist/kam.lua

rspamadm configtest && systemctl restart rspamd

Run rspamadm configtest first. Always. I’ll say it twice because someone reading this is going to skip it and restart straight into a syntax error at 2 a.m. with the queue backing up. The generated Lua compiles cleanly, but you still validate before you reload, because the one time you don’t is the one time the download truncated on a full disk.

One honest caveat. The big “800 ms versus 40 ms” number compares SpamAssassin-the-Perl-daemon against Rspamd. It is not a benchmark of Rspamd’s own SA compatibility module against this converter; both run inside the same regexp cache, so they’re in the same ballpark on raw scan speed. What the converter buys you over the SA module is correctness and hygiene: symbols that resolve, dead metas pruned, one reviewable file pinned to a known KAM.cf hash, and no 6,500-line parse on every reload. Anyone selling you a 20x speedup from the converter specifically is selling you the wrong number, and you should always check who’s holding the stopwatch.

The converter is MIT-licensed. The generated kam.lua is a derivative work of KAM.cf and inherits its Apache-2.0 license and authorship, so the credit stays with McGrail and the SpamAssassin crew where it belongs.

Frequently asked questions

Related reading

• Rspamd Explained: How Modern Spam Filtering Actually Works. Bayes, neural nets, RBLs, greylisting and the rest of the engine KAM.cf plugs into.
• How to Install ModSecurity and OWASP CRS on NGINX. The same defense-in-depth idea, applied to your web stack instead of your mail.
• Where To Find Us. All our repos, Docker images, and GitHub projects in one place.

Anyway. Go dump your Rspamd’s /symbols endpoint into external-symbols.txt before you build anything, because a converter that doesn’t know what your server can do will cheerfully drop half of KAM.cf and never tell you it mattered.

Welcome to the vibe-coded exploit era. The barrier to writing an attack tool used to be skill. Now it’s a prompt. That sounds terrifying until you realise the same thing that makes these tools easy to make also makes them loud, sloppy, and gloriously easy to catch. This is the part nobody tells the juniors: you don’t beat volume with cleverness. You beat it with layers, each one cheap, each one boring, each one catching the trash the layer above let through.

Let me walk you through the whole stack, from the firewall rule that drops a scan before it costs you a CPU cycle, all the way down to the PHP setting that saves your bacon when everything above it fails. Because it will. Something always gets through. The only question is what’s waiting for it when it does.

What a vibe-coded attack actually looks like on the wire

Here’s the thing about a tool an LLM wrote in thirty seconds: it has tells. Lots of them. Real attackers spend effort hiding. Vibe-coders spend effort shipping, and the model optimises for “works on the happy path,” not “evades a WAF.” So you get this beautiful pattern of self-incrimination.

The user-agent is usually a dead giveaway. python-requests/2.31.0. Go-http-client/1.1. curl/8.5.0 firing 400 requests a second. Nobody browsing your blog ships a default requests UA. The wordlists are recycled, the same /wp-login.php, /.env, /.git/config, /phpmyadmin sweep that every GitHub “scanner” repo has copied from the last one since 2019. The error handling is non-existent, so the tool keeps hammering a path that’s already returned 403 forty times, because the model never wrote a backoff. And the TLS handshake is naked: a stock Go or Python client has a fingerprint (its JA4 hash) as recognisable as a fingerprint at a crime scene, because the author never thought to randomise the cipher order. They didn’t know it was a thing.

That’s your edge. Every one of those tells is something you can match on, cheaply, before the request ever reaches your application. The defense isn’t one magic rule. It’s a sieve with six meshes, and the trash gets caught somewhere on the way down.

The whole picture: defense in depth, six layers

Before we go layer by layer, look at the shape of the thing. A request comes in at the top. Each layer drops what it can and passes the rest down. Whatever survives all six gets logged, studied, and fed back to the top so the next one dies sooner. That feedback loop on the right is the part most people skip, and it’s the part that turns a static wall into something that learns.

The golden rule of this diagram: every layer assumes the one above it failed. That’s not pessimism. That’s how you sleep at night. Now let’s build it.

Layer 1: rate limiting and the WAF

This is your front door and it does the most work for the least money. A mass scanner’s entire business model is volume. Take the volume away and most of them just fall over, because the author never wrote retry logic.

Start with rate limiting in nginx or Angie. Two zones: one for the general site, one tight zone for the login and API paths that bots love.

limit_req_zone $binary_remote_addr zone=general:10m rate=20r/s;
limit_req_zone $binary_remote_addr zone=login:10m rate=3r/m;
limit_conn_zone $binary_remote_addr zone=conns:10m;

server {
    limit_conn conns 20;

    location / {
        limit_req zone=general burst=40 nodelay;
    }

    location = /wp-login.php {
        limit_req zone=login burst=2 nodelay;
        limit_req_status 429;
    }
}

That rate=3r/m on the login path is not a typo. Three requests a minute. No human logs in faster than that, and a brute-force tool that expected to try ten thousand passwords now needs two days per IP. Most give up. The ones that don’t, Layer 4 handles.

On top of rate limiting, run a real WAF. ModSecurity with the OWASP Core Rule Set is the standard, and we have a full step-by-step guide to installing ModSecurity and the OWASP CRS on nginx if you’re starting from zero. The CRS is a giant pile of regexes that catch SQL injection, path traversal, command injection, the lot. Vibe-coded payloads get caught by it constantly, because the model generated a textbook ' OR 1=1-- that the CRS has matched since the Obama administration. Running WordPress? Our WordPress Hardening Plugin ships CRS-aware rules that block the common attacks without you editing a line of PHP, and the full writeup explains what it catches.

Start the CRS in DetectionOnly mode. I mean it. The day I flipped a fresh CRS install straight to blocking on a client site, paranoia level 2, I took down their checkout because a legitimate product description contained the word “select” near a quote. Six hours of my Saturday, gone, chasing a false positive that a week in detection mode would have shown me on day one.

SecRuleEngine DetectionOnly
SecDefaultAction "phase:2,log,auditlog,pass"
# After a week of clean logs, flip to:
# SecRuleEngine On
# SecDefaultAction "phase:2,log,auditlog,deny,status:403"

Then layer in cheap reputation filtering. You don’t need a paid threat feed to start. A map that drops the default scanner user-agents costs nothing and catches an embarrassing amount of vibe-coded traffic:

map $http_user_agent $bad_ua {
    default            0;
    ~*python-requests  1;
    ~*Go-http-client   1;
    ~*\bzgrab\b        1;
    ~*\bnuclei\b       1;
    ~*masscan          1;
    ""                 1;   # empty UA is almost always a bot
}

server {
    if ($bad_ua) { return 444; }   # 444 = drop the connection, no response
}

Return 444, not 403. A 403 is a polite “no” that tells the tool the path exists and the server is alive. 444 closes the socket with nothing. The scanner’s bad error handling does the rest: it logs a connection reset, shrugs, and moves on, having learned exactly nothing about you.

One war story for the road. Geo-blocking is tempting and mostly fine, but don’t blanket-ban entire countries without thinking about who lives there. I once watched a team block all of “Asia” with a GeoIP rule and then spend a frantic afternoon wondering why their own CDN’s Singapore PoP started failing health checks. Block what you must, allowlist what you need, and write a comment in the config saying why, because future-you will not remember.

Layer 2: TLS hardening and security headers

Layer 1 dropped the loud ones. Layer 2 shrinks how much you tell the rest. Every byte of metadata you leak is a byte a tool can match on, and a thinner fingerprint means more of those automated tools simply don’t know what they’re looking at.

Kill the old TLS. On a modern stack there is no reason to speak anything below TLSv1.2, and TLSv1.3 should be your floor wherever your client base allows it.

ssl_protocols TLSv1.3 TLSv1.2;
ssl_prefer_server_ciphers off;
ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;

Then stop introducing yourself to strangers. server_tokens off hides your exact nginx version, so a scanner can’t map you straight to a CVE list. On Angie there’s a bit more you can do, and if you want the gory details of running a hardened build, the whole point of our extended Angie package is that the security knobs are already turned the right way.

Now the headers. These are mostly about the second class of attack: not the scanner hitting your server, but the payload that tries to run in your visitor’s browser. Set them once, in a snippet you include everywhere.

add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header Content-Security-Policy "default-src 'self'; object-src 'none'; frame-ancestors 'self'; base-uri 'self'" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;

That always keyword matters more than it looks. Without it, nginx skips the header on error responses, which means your 404 and 500 pages ship naked. Guess which pages an attacker is most likely to be staring at? Right. Add always or the header is theatre.

A word on Content-Security-Policy, since it’s the one that pages you at 3 a.m. A tight CSP is the single most effective control against cross-site scripting, and it’s also the one most likely to break your own site the moment someone adds an inline script. Roll it out in Content-Security-Policy-Report-Only first, watch the violation reports, then enforce. The compression side-channel angle matters here too: if you’re serving secrets over a compressed, dynamic response, read up on the BREACH attack before you assume HTTPS alone has you covered. It doesn’t.

Layer 3: request validation at the edge

This layer is where vibe-coded tools really show their underwear. A human-written exploit is crafted to look plausible. An LLM-generated one is often syntactically valid garbage: a 40 MB request body to a login form, a PUT where a POST belongs, a path with a null byte in it because the model copied a 2008 Stack Overflow answer about bypassing file extension checks.

Cap the body size. Tightly. WordPress media uploads aside, most of your endpoints have no business accepting megabytes.

client_max_body_size 2m;

location = /xmlrpc.php { deny all; }   # nobody misses it

location = /wp-login.php {
    client_max_body_size 64k;
}

Whitelist methods. If an endpoint only ever sees GET and POST, say so, and watch the OPTIONS and TRACE probes bounce.

location /api/ {
    limit_except GET POST {
        deny all;
    }
}

nginx normalises paths before matching, which already eats a lot of the classic ../../../etc/passwd traversal noise, but don’t lean on that alone. The CRS from Layer 1 has dedicated traversal and null-byte rules, and they fire hard on exactly the kind of malformed input these tools spray. The combination is the point: nginx normalises, the CRS inspects, and the request that’s still standing is one a careful human wrote, which is a much smaller pile to worry about.

Here’s the trap nobody warns you about. merge_slashes is on by default, which collapses // into /. Sounds helpful. It also means a poorly written upstream auth check that keys on the literal path string can be bypassed with a doubled slash. The default is right for most people. Just know it’s there before someone files a bug claiming your access rules “randomly” don’t apply.

Layer 4: authentication and access control

Everything above is about cutting noise. This layer is about making sure the few requests that reach something sensitive have actually earned it. The single most effective thing you can do here costs nothing: take your admin surface off the public internet.

Your /wp-admin, your phpMyAdmin, your Grafana, your staging site. None of it needs to face the whole planet. Bind it to a VPN range or allowlist your own IPs and the entire category of “scanner finds login page, scanner brute-forces login page” evaporates.

location ^~ /wp-admin/ {
    allow 10.8.0.0/24;     # your WireGuard subnet
    allow 203.0.113.7;     # office static IP
    deny all;
}

# keep admin-ajax.php public, the front-end needs it
location = /wp-admin/admin-ajax.php { allow all; }

That admin-ajax carve-out is the gotcha. Block all of /wp-admin/ without it and half your plugins’ front-end features stop working, and you’ll get a “the site is broken” ticket before the page cache even expires. Ask me how I know.

Couple your WAF to fail2ban so repeated offenders get banned at the firewall, where blocking costs a single iptables/nftables rule instead of a full request cycle through nginx and ModSecurity.

# /etc/fail2ban/jail.local
[nginx-limit-req]
enabled  = true
filter   = nginx-limit-req
logpath  = /var/log/nginx/error.log
maxretry = 10
findtime = 60
bantime  = 3600

[nginx-badbots]
enabled  = true
port     = http,https
filter   = nginx-badbots
logpath  = /var/log/nginx/access.log
maxretry = 2
bantime  = 86400

For anything you actually expose, like an API, validate the credential properly. If you’re handing out JWTs, check the signature and the algorithm, because the classic alg: none bypass is exactly the kind of thing a vibe-coded tool will try, having read about it in the same blog post you did. Mutual TLS (mTLS) is the heavier hammer for machine-to-machine traffic: if the client can’t present a cert you issued, the handshake never completes and your application code never runs. No request, no attack surface.

Layer 5: the PHP layer, assume the WAF missed one

Every layer so far lived in front of your application. But the whole premise of defense in depth is that one day a request gets all the way through, and on a WordPress or PHP site, that request lands in the PHP interpreter. So you harden the interpreter too, on the assumption that it’s the last thing standing.

Start in php.ini. Stop announcing your version, and lock down the file system the interpreter can see.

expose_php = Off
display_errors = Off
log_errors = On
allow_url_fopen = Off
allow_url_include = Off
open_basedir = /var/www/html:/tmp
disable_functions = exec,passthru,shell_exec,system,proc_open,popen,pcntl_exec

That disable_functions line is the one that turns a successful file-upload exploit into a dead end. The whole point of dropping a PHP webshell is to call system() and run commands. Take those functions away and the shell the attacker just uploaded is an expensive way to print “hello.” It won’t stop every exploit. It absolutely wrecks the most common one.

The caveat: some plugins legitimately call exec(), and the day you blanket-ban it you might break a backup plugin that shells out to mysqldump. Test in staging. Read the error log. This is the recurring theme of the whole job, isn’t it. Every good hardening control breaks something the first time, and the difference between a senior and a junior is that the senior expected it.

For real teeth, run Snuffleupagus. It’s a PHP module that does virtual-patching and runtime hardening, the spiritual successor to the old Suhosin patch, and it can bind dangerous functions to specific call sites and kill the rest. We package it, and the ready-made myguard.rules ship inside our hardened Docker images on GitHub, because the default PHP posture is too trusting. Our step-by-step Snuffleupagus tutorial walks through writing those rules from scratch if you’d rather understand them than copy them. And keep an object cache like Redis or Valkey in front of your database so the brute-force login attempts that do slip through aren’t also hammering MySQL into the ground. If you’re weighing the options there, our writeup on Valkey, the Redis fork that actually won covers why we default to it now.

Layer 6: observability, or how you find out what got through

Here’s the uncomfortable truth. Something will get through. A WAF is a probabilistic filter, not a wall, and anyone who tells you their setup is unbreakable is selling something or hasn’t been breached yet. Layer 6 is the difference between learning about a compromise from your own dashboard and learning about it from a stranger on Twitter.

Log in a structured format you can actually query. JSON access logs turn “grep and pray” into real analysis.

log_format json_combined escape=json '{'
  '"time":"$time_iso8601",'
  '"ip":"$remote_addr",'
  '"status":$status,'
  '"method":"$request_method",'
  '"uri":"$request_uri",'
  '"ua":"$http_user_agent",'
  '"ja4":"$ssl_ja4"'
'}';
access_log /var/log/nginx/access.json json_combined;

That $ssl_ja4 field is the quiet hero. JA4 is a TLS client fingerprint (see the full write-up on how JA3/JA4 fingerprinting works), and because our Angie and nginx builds ship the JA4 module, you get the attacker’s handshake signature on every line. When a vibe-coded tool sweeps you, every request shares one JA4 hash, because the author never randomised the TLS stack. One hash, ten thousand requests, four hundred distinct paths, ninety percent 404s. That’s not a user. That’s a banner that says “ban me.”

Alert on the 4xx ratio, not just on errors. A sudden spike of 404s from a single IP or JA4 is a scan in progress. Pipe the logs into anything (Loki, an ELK stack, a cron job and a shell script if you’re scrappy) and trip an alert when one client crosses, say, fifty 404s in a minute.

And plant a honeypot. A path that no human or legitimate crawler should ever request, like /wp-admin-secret-backup/, with one job: any IP that touches it gets instantly added to your deny list. Real users never find it. Scanners, working from their recycled wordlists, find it constantly. It’s the cheapest, highest-signal trap you can set, and it feeds straight back to Layer 1. That’s the loop closing. The thing that got caught at the bottom teaches the top to catch it sooner next time.

Docker isolation: shrink the blast radius

Say the worst happens. The WAF missed it, the PHP hardening didn’t catch it, and an attacker has code execution inside your web container. Defense in depth says: fine, now what can they reach? If the answer is “the whole host as root,” you built a wall with a door behind it. If the answer is “a read-only filesystem, no capabilities, no other containers,” you’ve turned a breach into an inconvenience.

Run the container as a non-root user, read-only, with every Linux capability dropped and no ability to gain new ones.

services:
  web:
    image: angie:hardened
    read_only: true
    user: "1000:1000"
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run
    networks: [frontend]

A read-only root filesystem alone neutralises a huge class of exploits, because the attacker can’t write their toolkit anywhere persistent. cap_drop: ALL means even if they’re “root” inside the container, that root can’t load kernel modules, can’t mess with the network stack, can’t do most of what root implies. And network segmentation means the compromised web container can’t pivot to your database container, because they don’t share a network. This is the whole game: containment. We went deep on every one of these flags in the Docker hardening guide for self-hosters, so I won’t repeat the lot here. And it’s not theory: the same flags lock down our own hardened Roundcube webmail image, which runs as nobody and can chown nothing.

Patching: the boring layer that does the most

I saved the least glamorous one for last, because it’s the one that actually matters most, and the one juniors skip because it’s boring. Here’s the flat truth, no hedging: the overwhelming majority of “hacks” are not clever zero-days. They are a known CVE, with a patch available for months, against software nobody updated. The vibe-coded tool sweeping you isn’t smart. It’s just checking whether you did your homework.

So do your homework automatically. On Debian and Ubuntu, turn on unattended security upgrades and stop thinking about it.

apt install unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades

Keep your container images rebuilt on a schedule, not whenever you happen to remember. A “latest” tag you pulled eight months ago is not latest, it’s a museum piece full of CVEs. Our Angie and nginx Docker images rebuild daily for exactly this reason, so the base layer you pull from Docker Hub was patched this morning, not last winter. The reason this works: the gap between “CVE published” and “exploit tool ships it” is now days, sometimes hours, because the tool-maker can ask a model to write the exploit from the CVE description. The patch window has collapsed. Automated patching is no longer optional hygiene, it’s the only way to keep pace with automated attacks.

There’s a grim symmetry to it. The same AI that lets a kid write a scanner in one prompt also lets defenders find bugs faster, as the curl project discovered when AI tooling dredged up a record pile of vulnerabilities (and a flood of garbage reports alongside the real ones). If you run WordPress, we wrote up blocking these AI-driven attacks at the WAF layer separately. The arms race is real, both sides got a force multiplier, and the only people who lose are the ones running unpatched software and hoping.

Where to start tomorrow morning

You don’t build all six layers in one afternoon, and you shouldn’t try. Pick the cheapest, highest-impact wins first. Turn on rate limiting and the bad-UA map today, they take ten minutes and cut the noise immediately. Put the WAF in detection mode this week and read its logs before you flip it to blocking. Take your admin surface off the public internet this month. Turn on unattended-upgrades right now, before you close this tab, because that’s the one that quietly handles the attacks you’ll never even see.

The attackers got a force multiplier. So did you. The tools to build every layer above are free, open source, and mostly a few lines of config. The vibe-coders are betting you didn’t bother. Prove them wrong.

Anyway. Go check whether your last backup actually restores before you touch any of this. You did test it, right?

Right. Gather round, you lot. First week on the job, and I’m going to tell you the thing nobody told me: you cannot patch faster than a machine can find holes. You just can’t. So you do the next best thing. You put a wall in front of the hole and you wait for the patch to land. That wall is the wordpress-hardening-plugin: an open-source ModSecurity Core Rule Set plugin that bolts 40-odd WordPress-specific rules onto your web server’s edge. No PHP changes. No extra WordPress plugin to babysit. Nothing phoning home. Grab a coffee. We’re doing all of it.

So what even is a ModSecurity CRS plugin?

Quick map of the territory, because half of you are nodding along pretending you know. That’s fine. We all did.

ModSecurity is a Web Application Firewall (a WAF) that lives inside your web server (NGINX, Angie, Apache) and reads every HTTP request before your app ever sees it. On its own it knows nothing. It’s an empty engine with no brain. The OWASP Core Rule Set is the brain you bolt on: a curated, battle-tested library of rules for SQL injection, XSS, path traversal, the whole rogues’ gallery.

And since CRS 4.0 there’s a plugin system. Drop a couple of specially-named files into one directory, CRS loads them automatically, layered on top. No patching core. No forking. No merge hell when CRS updates next month. The wordpress-hardening-plugin is exactly that kind of drop-in.

Here’s what I mean. The stock CRS is a very good bouncer who knows every general troublemaker in the city. Problem is, your venue is a WordPress site, and WordPress has its own private list of regulars who cause grief: xmlrpc.php, ?author=1, wp-cron.php, the theme editor. This plugin hands the bouncer a laminated cheat-sheet of every WordPress-specific trick in the book. Same bouncer. Sharper instincts. And here’s the bit that matters: it stops them at the door, before PHP even wakes up.

The AI vulnerability wave, and why a WAF is suddenly your seatbelt

I’m going to say something the vendor brochures won’t. A WAF does not fix your vulnerabilities. It hides them. That used to be a slightly embarrassing thing to admit at conferences. Now? It’s the whole point. Let me explain, because this is the single most important thing you’ll learn this week.

The economics of finding bugs just flipped. It used to take a skilled human days to audit a plugin and dig out one exploitable orderby injection. Now an LLM does it across a thousand plugins over a weekend, and the same trick runs on both sides of the fence. The good guys disclose responsibly (the same models are already being turned loose as vibe-coded exploit scanners hitting your webserver). The bad guys don’t. The gap between “a bug exists in the plugin you installed and forgot about” and “a bot is firing the exploit at your site” has collapsed from months to hours.

But the defender’s loop hasn’t sped up to match. Think about it. The plugin author still has to read the report, write the fix, test it, ship it. You still have to notice the update and apply it. And across that gap, those hours or days where the bug is public and your site isn’t patched yet, something has to stand in the doorway and refuse to let the exploit through. That something is a WAF that actually understands WordPress.

So get this straight now and save yourself a bad night later: this plugin is a last line of defense and a time-buyer. Not a cure. It’s your seatbelt. Seatbelts are brilliant. They are also not a reason to drive into walls. The stuff at the end of this guide (update everything, lock down PHP, harden the box and the container) is the brakes and the steering. You want all of it. Honestly.

Why a WordPress hardening plugin for ModSecurity beats a PHP security plugin

Someone always asks this. Fair question. Wordfence, Sucuri, the rest: they exist, they’re not useless. But for a self-hosted site where you actually care about resources, doing your perimeter blocking at the WAF layer wins. Four reasons, and I want you to remember the first one especially.

• PHP never loads for a blocked request. When ModSecurity rejects something at the NGINX layer, WordPress doesn’t boot, PHP-FPM doesn’t fork, MariaDB never gets touched. A botnet hammering your login page burns almost none of your CPU. A PHP-based security plugin? By definition it has to boot PHP and WordPress before it can decide to block you, which is the exact resource fire you were trying to put out. You know that special hell where the site falls over because of the thing meant to protect it? The firewall cheerfully DDoSing you on the attacker’s behalf? Yeah. Avoid that.
• The guard isn’t standing inside the building it’s guarding. A PHP security plugin runs in the same process, with the same database access, as the code it protects. A WordPress-core zero-day or a bug in some other plugin can take it down with everything else. A rule in ModSecurity has zero exposure to WordPress-level bugs. Different process. Often a different privilege domain entirely.
• One file protects every site. Running twenty WordPress sites behind one NGINX? One plugin directory hardens all of them, the same way, every time.
• One less thing to trust. Every WordPress plugin you bolt on is another supply-chain dependency and another row in next year’s CVE firehose. This one lives outside WordPress completely.

Every rule, explained: the full inventory

No hand-waving. No “enterprise-grade protection” word salad (if anyone ever sells you that phrase, walk away). Here’s every protection the plugin ships, grouped by what it actually defends, with the real reasoning. Nearly all of it is a one-line toggle in plugins/wordpress-hardening-config.conf; I’ll call out the defaults as we go. Anything tagged PL2 only fires if you run CRS at paranoia level 2 or higher.

Access control & identity leaks

• Block xmlrpc.php (default: ON). A legacy RPC endpoint from the blogging-client era nobody remembers. Today it’s almost pure attack surface: system.multicall lets an attacker test thousands of passwords in one request, pingback enables DDoS amplification, and it exposes upload methods. Unless a specific mobile app needs it, it has no business being public. Localhost and private ranges stay whitelisted so your internal tooling lives.
• Block user enumeration (default: ON). WordPress hands out usernames via the ?author=1 redirect and the REST /wp/v2/users endpoint. No username, no targeted brute force. Blocks both. (The ?author=N form is always blocked; the readable /author/<slug>/ archive page is a separate toggle, below.)
• Block the literal username “admin” at login (default: ON). The single most-tried brute-force username on Earth is “admin”. If you don’t have a user named exactly that, and you shouldn’t, that’s day-one hygiene, this deflects a huge chunk of automated junk with basically zero false positives. It blocks the username “admin”, not your actual admins. Don’t panic.
• Block the /wp-json REST API (default: OFF). The REST API powers Gutenberg and half the plugin ecosystem, so blocking it wholesale breaks most sites. Hence off by default. For a headless or static setup where REST consumers live on an internal network, turning it on closes a real data-exposure surface.
• Block wp-cron.php (default: OFF). WordPress fakes cron by hitting wp-cron.php on visitor page loads. Inefficient, occasionally abusable. If you’ve wired up a real system cron (do it), public access is dead weight. Off by default so you don’t break sites leaning on the pseudo-cron; localhost stays whitelisted.
• Block /author/<slug>/ archive pages (default: OFF). The slug-form author archive also leaks login names. Most blogs expose these on purpose, so it’s off by default; flip it on if author pages aren’t part of your public surface.

File, path & secret leaks

• Block direct PHP execution and directory listing in /wp-content/ and /wp-includes/ (default: ON). Real WordPress runs through index.php. Direct PHP execution in these trees is either a misconfig or someone running a webshell. Directory listing turns a missing index.html into a free site map for the attacker.
• Block sensitive extensions: .db .orig .sql .log .git (default: ON). Developers leave things lying around. They just do. Database exports, editor backups, SQLite files, logs, exposed .git/HEAD. Scanners find these on production sites every single day.
• Block VCS and dotfile probes: .env, .git/, .svn/, .hg/, .bzr/, .htpasswd, .DS_Store (default: ON). The .env file is the modern crown jewel: database password, API keys, mail creds, all in one tidy file. Bots scan for it constantly. Constantly.
• Block wp-config.php backup variants (default: ON). .save, .old, .new, .dist, .sample, .copy, a trailing ~, numeric .1/.2. Every editor and every tired admin generates one eventually, and any of them serves your database credentials in plaintext to whoever types the URL. Usually the bored teenager currently scanning your /24.
• Block backup directories & archives (default: ON). UpdraftPlus, BackWPup and friends sometimes drop .zip/.tar.gz/.tar.bz2 into web-reachable paths. That’s your whole site in one click.
• Block compressed database dumps: .sql.gz, .sql.bz2, .sql.zip (default: ON). A migration leftover that contains every password hash, every email address, every post you’ve ever written. Found more often than you’d believe.
• Hard-block info-leak paths in phase 1 (default: ON). readme.html, license.txt, .user.ini, wp-admin/install.php, wp-admin/setup-config.php, wp-includes/wlwmanifest.xml, wp-content/debug.log. This one fires in phase 1, before any upstream redirect can sneak ahead of ModSec. That readme.html version string is exactly how a scanner learns your WordPress version and which CVEs to throw.
• Block plugin/theme readme.txt version probes (default: OFF). Scanners read /wp-content/plugins/<slug>/readme.txt to map installed plugin to known CVE. Off by default because legit tooling (wp-cli) reads these too; turn it on if you accept that trade.

Upload abuse & remote code execution

• Block nasty files in /wp-content/uploads/ (default: ON). The uploads directory is world-writable by design. It’s where the cat photos go. It’s also the favourite landing zone for a webshell smuggled in through a vulnerable plugin. Requests for executable or dangerous extensions there get blocked.
• Block directory traversal in uploads (default: ON). ../ and its URL-encoded cousins inside /wp-content/uploads/ requests: the trick that turns a sloppy file-serving function into “read me /etc/passwd, would you.”
• Block alternative interpreters: .pl, .lua, .py, .sh (PL2). If your server is ever misconfigured to run these over HTTP, a file-upload bug becomes full remote code execution. This slams that door.
• Block PHP stream wrappers in arguments (default: ON). php://, data://, expect://, file://, phar://, glob://, zip://, compress.zlib://, compress.bzip2:// anywhere in a parameter or the URI. Classic local/remote file inclusion. phar:// deserialization alone has powered a decade of WordPress RCE chains.
• Block null-byte injection (PL2, default: ON). %00 in the URI or parameters truncates strings in C-based code, beats extension checks (shell.php%00.jpg), confuses parsers. No legitimate request has ever contained one. Not once.

Reconnaissance & version disclosure

• Block the exact /wp-json path (default: ON). Even with full REST blocking off, the bare /wp-json root returns a manifest of every registered endpoint: a free map of your attack surface. This blocks the map while leaving the API itself working.
• Detect version-disclosure response headers (default: tag). X-Pingback, X-Powered-By, and the REST Link: rel="https://api.w.org/" header all whisper your software versions. ModSecurity v2 can’t strip response headers, so the plugin flags them and you do the actual removal at the proxy: proxy_hide_header X-Pingback; proxy_hide_header X-Powered-By; more_clear_headers "Link";
• Block XDebug & phpinfo probes (default: ON). XDEBUG_SESSION triggers and phpinfo probe parameters. A live phpinfo on production is a catastrophic leak, and this is exactly how bots go looking for it.
• BREACH compression side-channel tagging (default: tag). Requests to /wp-admin/, /wp-login.php and /wp-json/* get flagged so you can confirm your proxy strips Accept-Encoding on those paths. The real fix lives in the server. Our deep dive on the BREACH attack explains why compressing secret-bearing responses leaks them.
• Block known security scanners (PL2, default: OFF). nikto, sqlmap, wpscan and pals by user-agent. Off by default (UA blocking is trivially bypassed and real pen-testers use these) but a handy noise-reducer on a heavily-scanned box. Heads up: the bundled list also catches SEO crawlers like Ahrefs and Semrush, so read the README before flipping it if you care about those.

Known CVEs & HTTP hygiene

• Block actively-exploited plugin CVEs (default: ON). Signatures for SureTriggers / OttoKit (CVE-2025-3102, CVE-2025-27007, unauthenticated admin creation) and Bricks Builder (CVE-2024-25600, unauthenticated RCE). Turn it off only if you genuinely run those plugins and need their REST traffic.
• Block legacy CVE scanner probes (default: ON). revslider, timthumb, WP Symposium, MailPoet’s wysija_captcha, wp-file-manager’s connector.minimal.php, Duplicator installer leaks. Long dead. Still scanned hourly. Pure log-noise reduction; no legit request hits these.
• Block uncommon HTTP methods (default: ON). TRACE/TRACK/DEBUG/PROPFIND/MKCOL/COPY/MOVE/LOCK/UNLOCK/PUT/DELETE/PATCH on /wp-admin/, /wp-login.php, /xmlrpc.php, /wp-cron.php. /wp-json is deliberately exempt, because authenticated REST writes legitimately use PUT/DELETE/PATCH.
• Block CVE-2018-6389 DoS (default: ON). A long ?load= list on wp-admin/load-scripts.php or load-styles.php makes WordPress concatenate dozens of files per request and cook your CPU. Anonymous, unauthenticated, still works on unpatched cores. Blocked.
• Block dangerous wp-admin endpoints (default: ON). upgrade.php and wp-activate.php, rarely reached on a settled site. (install.php and setup-config.php are already hard-blocked in phase 1 above.)
• Block code injection in login fields (default: ON). <script>, eval(, base64_decode, onload=, onerror= in the log and pwd POST parameters of wp-login.php. Those are the username and password boxes. Nobody’s real password is a <script> tag.

The new front line: typed-parameter SQLi & XSS rules

Okay. Pens down, eyes up. This is the part written specifically for the AI wave, and it earns its own section because it works differently from everything above. Rules 9522330 through 9522334. If you remember one thing from today, make it this.

Here’s the thing nobody tells the new starters: the stock CRS already hunts for SQL injection and XSS in every parameter. It uses a library called libinjection, and at paranoia level 1 it runs on everything. So why add more? Because libinjection is a generalist pattern-matcher, and the single most common WordPress plugin SQL injection, the ORDER BY injection, is precisely the case it has documented bypasses for. Maddening, right? The most common bug is the one the generic tool is weakest at.

Quick lesson, because this genuinely is the most important bug class in the current wave. SQL has a clause: ORDER BY column ASC. And you can’t parameterise a column name or a sort direction the way you can a value, so lazy plugin code just jams $_GET['orderby'] and $_GET['order'] straight into the query. An attacker sends orderby=id-(case when (1=1) then 1 else 0 end) and now your database is happily answering true/false questions about its own contents. No quotes. No SELECT keyword. Nothing that looks like the textbook injection libinjection was trained on. Slips right past.

The plugin’s answer isn’t to play whack-a-mole with cleverer signatures. It’s to use types. A sort direction can only ever be asc or desc. A column name can only ever be letters, digits, underscores, dots. So:

• 9522330: order= must be asc or desc (default: ON). Anything else, blocked outright. There is no legitimate third value. The admin-ajax reorder vector that uses order[]= arrays is deliberately not matched, so your drag-to-reorder UIs keep working.
• 9522331: orderby= may not contain SQL metacharacters (default: ON). Quotes, parens, comment markers, SQL keywords: rejected. Bare column names, including multi-column title,date, pass clean.
• 9522332: strict orderby= allowlist (PL2). At paranoia level 2, orderby must match a plain column-name pattern and nothing else. Stricter, for the cautious among you.
• 9522333: WordPress core numeric query-vars must be integers (default: ON, zero false positive). p, page_id, attachment_id, m, w, year, monthnum, day, hour, minute, paged, cpage are integers by definition in WordPress core. A <script> or a UNION SELECT in any of them is, with certainty, an attack. (cat and author are excluded; they legitimately take comma-separated and negative lists.)
• 9522334: strict integer enforcement on generic id params (PL2, default: OFF). id, post_id, user_id, term_id, parent_id, comment_id. These names are generic enough that some plugins (mis)use them for non-integers, so it’s opt-in and only fires at PL2. But when your plugins behave, it’s a wall across the most-injected parameter names in the catalogue.

Why is this stronger than a signature? Think about it this way. An allowlist doesn’t care how clever the payload is. A blocklist asks “does this look like an attack I’ve seen before?”, and a motivated attacker just makes their attack look new. An allowlist asks “is this one of the handful of values that are actually legitimate here?” And for a sort direction, that’s a closed set of two. You cannot obfuscate your way into being the word asc. That’s the whole game. Allowlist the things you can; you’ll sleep better.

Three teeth that aren’t just pattern matching

Signatures can’t cover everything. Three features add stateful, identity-aware defense, and I’m going to be straight with you about their sharp edges, because the README is, and you deserve the same. A tool that lies about its weaknesses is worse than no tool.

IP-based rate limiting for wp-login.php

A slow, distributed brute force (one guess every few seconds from a rotating botnet) sails past signature rules forever. Rate limiting closes that. The plugin counts POST requests to /wp-login.php per resolved client IP using ModSecurity’s persistent collections, and after the threshold it blocks everything further from that IP until the window expires, returning a proper HTTP 429 Too Many Requests (RFC 6585). Default: 5 attempts per 60 seconds, both tunable.

# Tighten to 3 attempts; windows must be one of 30/60/120/300/600
SecAction "id:9522049,phase:1,nolog,pass,t:none,setvar:'tx.wphard.ratelimit_login_attempts=3'"
SecAction "id:9522050,phase:1,nolog,pass,t:none,setvar:'tx.wphard.ratelimit_login_window=30'"

And here’s the sharp edge, the one that’ll bite you if I don’t say it now. Persistent collections work reliably on Apache + mod_security2. On libmodsecurity3, the engine NGINX and Angie use, the collection implementation has long-standing gaps, and the counter often just never persists across requests. So if you’re on NGINX (most of you will be), do your login rate-limiting in the server instead with limit_req zone=..., and treat this feature as Apache-only. There’s also a collection-growth footgun: each unique IP creates an entry, so on a directly-exposed box set SecCollectionTimeout 300 and turn on trusted-proxy pinning (below) before someone rotates IPv6 addresses to bloat your data dir. A firewall that fills your disk is just a slow, self-inflicted outage with your name in the post-mortem. Don’t be that ticket.

GeoIP access control for wp-login.php

If your admins are all in the Netherlands and Germany, why is wp-login.php reachable from anywhere else on the planet? Maintain an allowlist of ISO country codes; everyone outside gets blocked before WordPress loads. The clever bit: no GeoIP database is needed on the WAF. Your upstream already knows the country. Cloudflare sets CF-IPCountry, NGINX with ngx_http_geoip2_module (in our optimized NGINX builds) sets X-GeoIP-Country, and ModSecurity just reads the header.

# plugins/wordpress-hardening-login-countries.data  (lowercase, one per line!)
nl
de
gb

Off by default, fail-open (a missing header lets the request through, so a proxy misconfig can’t lock you out), and the lookup is case-sensitive. Write NL instead of nl and you’ll block every login including your own, then spend twenty minutes convinced the plugin is broken. Ask me how I know. Go on, check your data file. I’ll wait.

IP reputation blocklist

The most aggressive option: block all requests from known-bad IPs, not just logins. A plain-text file of IPs and CIDRs, loaded with @ipMatchFromFile and checked on every request. The plugin ships the mechanism; you supply the data from a threat feed (Spamhaus DROP, Emerging Threats, Firehol Level 1) via a cron job that refreshes the file and reloads NGINX. Off by default. Loopback and private ranges are always immune, so you can’t blocklist your own infrastructure by accident. (You’d be amazed.)

IP whitelisting, so you don’t lock yourself out

Every IP-aware feature (the blockable endpoints, the rate-limit counter, the GeoIP gate, the reputation list) shares a single client-IP resolver and a single “is this a private IP?” decision, so the same identity is used everywhere. Out of the box it whitelists IPv4 loopback and RFC 1918, plus IPv6 ::1 and ULA fc00::/7. Your cron jobs, monitoring, and load-balancer health checks won’t trip a thing.

The resolver defaults to REMOTE_ADDR and, if present, takes the leftmost hop of X-Forwarded-For. Which raises a footgun worth naming out loud: on a directly-exposed server, an attacker can forge X-Forwarded-For to fake a trusted private IP and skate past the whitelist, or rotate it to dodge the rate-limiter. The fix is trusted-proxy pinning: list your real upstream proxy CIDRs in a data file and enable it, and XFF is honoured only when the connecting peer is actually one of your proxies. It’s off by default for backward compatibility. If your box has a public IP, turn it on. Today.

How to install it

Standard CRS plugin install. You need CRS 4.0+ and a ModSecurity-compatible WAF (ModSecurity v2/v3 or Coraza). No WAF yet? Start with our step-by-step guide to ModSecurity and the OWASP CRS on NGINX, then come back and layer this on top.

# 1. Go to your CRS plugins directory
cd /etc/nginx/modsecurity.d/owasp-crs/plugins/

# 2. Clone the plugin in place
git clone https://github.com/eilandert/wordpress-hardening-plugin .

# 3. CRS auto-loads plugins/*-config.conf, *-before.conf, *-after.conf

# 4. Test config and reload
nginx -t && systemctl reload nginx

That’s it. Every sensible default is live immediately; open plugins/wordpress-hardening-config.conf to tune. I’d also strongly grab the companion wordpress-rule-exclusions-plugin, which suppresses the CRS false positives WordPress naturally trips (Gutenberg’s POST bodies are absolutely feral). Add protection, not noise. That’s the whole job, really.

A WAF is the last line, not the only one

And now the lecture you came here to skip and actually need to hear. So sit back down. This plugin buys you time. It does not buy you immortality. Install it, then stop patching, and you’ve built a lovely fence around a house with the doors hanging open. Defense in depth means layers, and the WAF is one of them. Here are the others, ranked by how often people skip them.

• Update and upgrade. Religiously. WordPress core, every plugin, every theme, PHP itself, the OS packages. The whole point of the AI wave is that the gap between disclosure and exploitation is now hours. Auto-update what you safely can; for the rest, check weekly and treat a pending security update like a smoke alarm, not a notification you’ll get to eventually. The breach-disclosure email you send your users is always longer than the changelog you didn’t read. The WAF covers you across that gap. It is not permission to widen it.
• Lock down PHP with Snuffleupagus. Even if an exploit gets past the WAF and reaches PHP, you can stop it doing damage. php-snuffleupagus is a PHP module that virtual-patches whole bug classes: disable system() calls that don’t match a whitelist, block phar:// deserialization, neuter dangerous ini_set calls, cookie-encrypt sessions. It’s the difference between “the exploit ran” and “the exploit ran, then hit a wall inside the interpreter.”
• Harden the web server. TLS done right, security headers, sane timeouts, request-size limits, the WAF itself tuned properly. Our expert guide to NGINX and Angie performance and security is the long version. Short version: defaults are for getting started, not for production.
• Harden the container. If WordPress runs in Docker (and it should), run it rootless, read-only, capabilities dropped, no-new-privileges set, so a compromise inside the container is a compromise of nothing useful. Our Docker hardening checklist walks the whole thing: rootless, read-only root filesystem, cap-drop, distroless, network segmentation.

Stack those and an attacker has to beat your WAF, and find an unpatched bug, and get past Snuffleupagus, and break out of a locked container, instead of beating one sloppy PHP plugin. That’s defense in depth. The wordpress-hardening-plugin is the first wall they hit. It should never be the last.

Design philosophy & how it’s tested

A few design choices worth understanding, because they change how you deploy it.

• No PHP, no MySQL, no WordPress in the hot path. Every rule fires at the ModSecurity layer. Under a real attack, that’s the difference between staying up and falling over.
• One toggle per feature. Each blocking group is gated by a TX:wphard.* variable read in phase 1. Disabling anything is one commented line in the config. No editing rule bodies, no risk of snapping the chain.
• Paranoia-level aware. Rules are tagged PL1 or PL2. Run a strict PL2 setup and the extra rules engage automatically; stay on PL1 (right for most sites) and you get the core protection without the PL2 chatter.
• Honest about its own limits. The README documents the libmodsecurity3 rate-limit gap, the collection-growth DoS, and the known false-positive patterns, instead of hiding them. Trust is built on the weaknesses you admit, not the strengths you advertise.
• Tested on every commit. The repo carries a full go-ftw suite: positive regression tests for each rule, a false-positive corpus of legitimate WordPress traffic that must never trip a rule, and a bypass-evasion corpus of obfuscated attacks that must always be caught. It runs against real nginx+libmodsecurity3 and Apache+mod_security2 containers. Rules don’t ship unless all three corpora pass.

There’s even a self-healing touch I’m a bit fond of: a built-in rule (9522801) suppresses three noisy CRS data-leakage rules on front-end blog permalinks only, so a tutorial site that publishes <?php snippets in its posts doesn’t get its own articles blocked by the outbound filter. Admin, login and API paths keep the full protection. That bug was found in production, on this very site, and fixed in the plugin. Dogfooding works. Sometimes it bites first.

Related reading

• How to Install ModSecurity and OWASP CRS on NGINX: build the WAF foundation first, then add this plugin.
• PHP Snuffleupagus Tutorial: Harden PHP-FPM: the in-interpreter layer that catches what gets past the WAF.
• Docker Hardening for Self-Hosters: rootless, read-only, cap-drop, distroless. Contain the blast radius.
• How to defend your webserver against vibe-coded AI exploit scanners and bots: the wave this plugin defends against, in one case study.
• Nginx & Angie: The Expert Guide to Maximum Performance and Security: harden the server the WAF runs in.
• NGINX Modules: Optimized & Extended: our builds ship the http-modsecurity and geoip2 modules precompiled.

Frequently asked questions

The wordpress-hardening-plugin is open source (Apache-2 licensed) and maintained at github.com/eilandert/wordpress-hardening-plugin. CRS 4.0+ required; works with ModSecurity v2, v3 and Coraza.

Related: HTTP/2 Bomb (CVE-2026-49975), another vulnerability an AI found, and how to defend it at the edge.

Which brings us to Dovecot, the quiet workhorse that’s been holding your email together while you weren’t looking. If you’ve ever read a mail header and felt a flicker of dread, this one’s for you. We’re going to take Dovecot apart, explain what cryptography actually does under the hood (no hand-waving), wire in genuine post-quantum key exchange, lock down every cipher that has any business being shot behind the barn, and bolt on Sieve so your inbox files itself. And we’ll do it the way the Bastard Operator From Hell would: with contempt for defaults, suspicion of every open port, and a container that trusts absolutely nobody.

What Dovecot actually is (and why you already depend on it)

Dovecot is an IMAP and POP3 server. That’s the boring one-liner. The useful version: it’s the piece of software that lets your phone, your laptop, and that one ancient Thunderbird install all see the same mailbox, in sync, over an encrypted connection. When Postfix or another MTA accepts a message from the outside world, it hands it off for local delivery, and Dovecot is what stores it, indexes it, and serves it back when a client connects on port 993 (IMAPS) or 995 (POP3S).

It’s the most popular IMAP server on the public internet by a wide margin, surveys have put it north of 70% of all IMAP-capable hosts for years. There’s a good reason for that dominance. Dovecot is fast (its index format is built for the access patterns mail clients actually use, not the ones a textbook assumes), it’s pedantically standards-compliant, and its security record is genuinely excellent for software this widely deployed. Timo Sirainen, the original author, was famously willing to pay out of his own pocket for any security hole found in the core. That kind of confidence is rare and earned.

Dovecot also does more than serve mail. It runs LMTP (the local delivery protocol that lets your MTA drop messages straight into Dovecot’s storage), ManageSieve (so users can edit their own mail-filtering rules), and a SASL auth service that Postfix leans on to decide who’s allowed to send mail. In a modern stack, Dovecot isn’t a leaf node, it’s load-bearing. If you’re running a mail server at all, you should treat its config like you treat your SSH config: paranoidly.

Crypto in ninety seconds, properly this time

Before we talk post-quantum anything, let’s get the foundations right, because most “TLS hardening” guides skip the part that actually matters.

When your client connects to Dovecot over TLS, three different jobs happen, and people constantly conflate them:

1. Key exchange (the asymmetric part)

Your client and the server need to agree on a shared secret over a wire that’s being watched. They do this with asymmetric cryptography, maths where a public value can be shared openly but a private one stays secret. Modern TLS uses ECDHE: Elliptic Curve Diffie-Hellman, Ephemeral. “Ephemeral” is the important word. A fresh key is generated for every single session and thrown away after. This gives you forward secrecy: even if someone steals the server’s long-term private key next year, they still can’t decrypt the session they recorded today, because the ephemeral key that protected it never touched disk and no longer exists. Forward secrecy is non-negotiable. Any cipher that lacks it, anything starting with plain RSA key exchange, belongs in a museum.

2. Authentication (the signature part)

Key exchange stops eavesdropping, but it doesn’t stop someone pretending to be your server. That’s what the certificate is for: the server signs part of the handshake with the private key matching its public certificate, and a CA you trust vouches for that certificate. This is where the “is this really mail.example.com?” question gets answered.

3. Bulk encryption (the symmetric part)

Once both sides share a secret, they switch to fast symmetric crypto for the actual data, your IMAP commands, your messages, your folder list. This is AES-GCM or ChaCha20-Poly1305. Both are AEAD ciphers: Authenticated Encryption with Associated Data, meaning they encrypt and tamper-detect in one pass. If an attacker flips a bit, the connection dies instead of quietly delivering corrupted data. The bad old CBC-mode ciphers didn’t do this cleanly, which is exactly how attacks like BREACH and its CBC cousins got their teeth. We turn CBC off entirely.

Here’s the thing that should make you sit up: a quantum computer threatens exactly one of these three. Symmetric crypto (AES, ChaCha20) is basically fine, Grover’s algorithm halves the effective key length, so AES-256 still gives you a comfortable 128 bits of quantum security. The thing that shatters is the asymmetric key exchange. Shor’s algorithm turns the hard maths behind RSA and elliptic curves into a tractable problem. The padlock holding your session secret is the part that breaks.

Dovecot post-quantum TLS and harvest-now-decrypt-later

So we have a clear, bounded threat: when a cryptographically relevant quantum computer arrives, every ECDHE and RSA key exchange ever recorded becomes decryptable. Not future traffic, recorded traffic. Anything an adversary stored on tape today.

That’s the harvest-now-decrypt-later attack in full. It doesn’t require the quantum computer to exist yet. It only requires an adversary patient enough to keep your encrypted blobs until one does. For most web traffic, a cat photo, a session that expires in an hour, who cares. For mail? Mail is forever. The contents of your inbox in 2026 may be every bit as sensitive in 2034. Email is the canonical worst case for HNDL, which is precisely why Postfix 3.11 shipped post-quantum TLS and why your IMAP server has no excuse to lag behind.

The fix is a new family of algorithms whose hardness doesn’t collapse under Shor’s algorithm. NIST ran a multi-year competition and standardised the winners in 2024. The key-exchange winner is ML-KEM (Module-Lattice Key Encapsulation Mechanism, FIPS 203, formerly known as Kyber). It’s a lattice-based KEM, and the lattice problems it relies on have no known efficient quantum attack.

But, and this is the part the marketing skips, nobody fully trusts a brand-new algorithm on its own yet. Lattice crypto is young. So the sane deployment is a hybrid: combine the classical, battle-tested X25519 elliptic-curve exchange with ML-KEM-768, and derive your session secret from both. An attacker now has to break both the lattice maths and elliptic curves to win. If ML-KEM turns out to have a flaw, you’re no worse off than classical TLS. If quantum computers arrive, X25519 falls but ML-KEM holds. You lose only if both break, and if that happens, we have bigger problems than your email. That hybrid group is called X25519MLKEM768, and it’s the de-facto default that browsers and OpenSSL already negotiate.

Wiring real PQC into our Dovecot

Here’s where theory becomes config. Post-quantum key exchange in Dovecot isn’t a Dovecot feature at all, it’s an OpenSSL feature that Dovecot inherits, because Dovecot is built with --with-ssl=openssl and links the system library. Hybrid ML-KEM landed in OpenSSL 3.5. No OpenSSL 3.5, no post-quantum handshake, full stop.

That single fact drove a deliberate decision in our package: we build Dovecot only for Debian trixie and Ubuntu resolute, the two suites that ship OpenSSL 3.5+. Older distros (bookworm, jammy, noble, bullseye) carry OpenSSL 3.0 or 1.1 and physically cannot negotiate ML-KEM. Building for them would be shipping a security promise we couldn’t keep. So we don’t.

The TLS config itself lives in conf.d/10-ssl.conf, and it’s where the BOFH energy goes. The key-exchange group list puts the post-quantum hybrid first:

ssl_curve_list = X25519MLKEM768:X25519:X448:secp384r1:secp256r1

Read that as a preference order. A modern client that speaks ML-KEM gets the post-quantum hybrid. A client that doesn’t falls back gracefully to classical X25519, still forward-secret, still strong, just not quantum-resistant. Nobody gets locked out; everybody capable gets the best available. That’s the whole philosophy.

For the symmetric ciphers, we keep only AEAD suites and shoot everything else:

ssl_cipher_suites = TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
ssl_cipher_list   = ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:\
                    ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:\
                    ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
ssl_server_prefer_ciphers = yes
ssl_min_protocol = TLSv1.2

What got the bullet: kRSA (no forward secrecy), all DH(E) and 3DES and DES, RC4, MD5, SHA1-MAC, every CBC suite, PSK, SRP, NULL, EXPORT. If a cipher was ever in a CVE title, it’s gone. We set ssl_server_prefer_ciphers = yes so the server dictates the ordering, we don’t let a client downgrade us into something weaker because it asked nicely. TLS 1.3 is negotiated whenever the client can; TLS 1.2 stays as a hardened fallback (forward-secret AEAD only) so we don’t break older-but-not-ancient clients. TLS 1.0 and 1.1, being thoroughly broken, are simply not on the menu.

The rest of the hardening: an IMAP server that trusts nobody

TLS is the front door. The BOFH worries about the whole house. Our dockerized Dovecot is built to a single principle: assume the process will be compromised, and make that compromise worthless.

Privilege separation, caged. Here’s where a lot of “hardened” images get it backwards. Dovecot is built around privilege separation: a small root master process binds the ports and loads the TLS key, then immediately hands every network-facing job to an unprivileged user. The processes that actually parse hostile input off the internet, the pre-auth IMAP/POP3 login workers, run as dovenull, a user that owns nothing. The processes that touch your mail run as vmail (uid 5000). Root never reads a byte from an attacker. Collapsing all that to a single uid (which a lot of “fully unprivileged” containers do) actually weakens you: a bug in the login parser would then already be running as the mailbox owner. So we keep Dovecot’s separation and cage the root master instead, cap_drop: ALL, then add back only the handful of capabilities it genuinely needs (drop privilege to dovenull/vmail, chroot the login workers, own its runtime sockets), plus no-new-privileges, AppArmor, and every setuid bit stripped out of the image. As a bonus we move every listener to a high port inside the container (via conf.d/99-unprivileged-ports.conf) and map the real public ports down to them host-side, so we don’t even need CAP_NET_BIND_SERVICE. Pop the login worker and you’re dovenull in a chroot with no capabilities and nowhere to go.

Read-only rootfs. The filesystem is immutable. The only writable surfaces are the mail volume, your config mount, and a few small tmpfs mounts the daemon needs at runtime (/run for its sockets, /var/lib/dovecot for its instance registry, and a noexec /tmp that $HOME points at, pyzor and razor insist on writing a dotfile somewhere). Everything else is carved in stone. Drop a webshell and it’s got nowhere to live, and because /tmp is mounted noexec, nowhere to run even if it did.

Architecture-independent malloc tuning. The image runs unchanged on amd64 and arm64; the LD_PRELOAD’d allocator (mimalloc or jemalloc) is selected at runtime by resolving the multiarch lib dir in bootstrap.sh, so there’s no per-arch image to maintain.

And the binaries themselves are hardened at compile time, not just at runtime. Our Dovecot package builds with -D_FORTIFY_SOURCE=3 (tighter buffer checks than the usual level 2), -fstack-clash-protection, -fcf-protection=full for Intel CET branch-target enforcement on amd64, -fno-plt to shrink the PLT-overwrite attack surface, and full RELRO with bindnow. None of these break old hardware, they’re no-ops on silicon that lacks the feature, but they make memory-corruption exploitation genuinely harder on hardware that has it.

Sieve: your inbox filing itself

Now the fun part, because security without convenience just trains users to disable it.

Sieve (RFC 5228) is a small, deliberately limited scripting language for filtering mail at delivery time, on the server, before your client ever sees it. It’s implemented in Dovecot by the Pigeonhole plugin, which tracks Dovecot’s release cycle tag-for-tag (our build resolves both from matching version tags). The language is intentionally not Turing-complete, no loops, no shell-out, no way to wedge the delivery agent in an infinite loop. That constraint is a feature: a hostile or buggy Sieve script can misfile your mail, but it can’t take down the server.

A trivial example that files everything from your mailing list into a folder and drops obvious spam:

require ["fileinto", "mailbox"];

if header :contains "List-Id" "debian-devel" {
    fileinto :create "Lists/Debian";
}
if header :contains "X-Spam-Flag" "YES" {
    fileinto "Junk";
    stop;
}

The killer feature is that users can manage their own Sieve scripts over ManageSieve (port 4190) without touching the server filesystem, Thunderbird, Roundcube and friends all speak it. And Sieve’s vnd.dovecot.execute extension is what lets you wire spam-reporting into the delivery pipeline, which is exactly where the next section comes in.

Batteries included: rspamc, spamc, pyzor, razor and the vimbadmin scripts

A bare IMAP server is half a mail stack. Our dockerized image ships the other half, the spam-fighting and administration tooling that a real deployment needs, so you’re not apt install-ing things into a “temporary” container that somehow becomes production.

Inside the image you get the full spam-reporting client set: rspamc and spamc (the command-line clients for Rspamd and SpamAssassin respectively), plus pyzor and razor, two collaborative spam-fingerprinting networks. These aren’t decoration. Wire them into a Sieve script and “report this as spam” becomes a one-line filter action: the message gets fingerprinted, the fingerprint is fed back to the network, and Rspamd’s Bayesian classifier learns from it. Move a message to Junk, and the whole feedback loop fires. That’s how a self-hosted server gets smarter over time instead of staying as dumb as the day you installed it.

The image also bundles the vimbadmin helper scripts, the Perl glue that lets ViMbAdmin, the Postfix + Dovecot mailbox admin panel, drive Dovecot for quota reporting and mailbox operations. ViMbAdmin gives you a proper web UI (with TOTP and brute-force protection) for managing virtual domains, mailboxes and aliases, instead of writing raw SQL into your mail database at two in the morning. The helper scripts are what connect that web panel to Dovecot’s actual mailbox state. And because the whole thing pulls its packages straight from the deb.myguard.nl APT repository baked into the base image, every component is the same hardened build, signed by the same key.

And when Sieve needs to send mail outward, a redirect that forwards a copy elsewhere, a vacation auto-reply, a notify, the container doesn’t run its own MTA at all. There’s no sendmail binary in the image, nothing to exploit. Instead Dovecot hands the outbound message over SMTP to the real Postfix container via submission_host. Mail access is Dovecot’s job; mail transport is Postfix’s, with all the queueing, retries, DKIM and bounce handling that implies. One egress point, one place to sign and rate-limit, and the smallest possible attack surface on the mailbox server itself.

Putting it together

Pull the picture back and the design philosophy is consistent at every layer. The crypto is post-quantum where it counts and forward-secret everywhere. The cipher list is AEAD-only and the protocol floor is TLS 1.2. The root master is caged behind dropped capabilities and no-new-privileges, hands every hostile byte to an unprivileged separated user, and sits on a read-only filesystem. The binaries are fortified, CET-protected and RELRO-locked. The spam pipeline learns. The admin happens through a hardened web panel instead of raw SQL. And the whole thing is two distros wide on purpose, because we’d rather ship a smaller promise we can actually keep than a bigger one we can’t.

Your mailbox is going to outlive the cryptography currently protecting it. The only question is whether someone’s keeping a copy of the handshake. Build for the answer being yes.

Frequently Asked Questions

Related reading

• Postfix 3.11: Post-Quantum TLS, TLSRPT, Milters and the Modern MTA Stack: the MTA half of the stack, with the same post-quantum TLS story on the sending side.
• ViMbAdmin: The Postfix + Dovecot Mailbox Admin Panel: the web UI that manages the virtual domains and mailboxes Dovecot serves.
• Rspamd Explained: How Modern Spam Filtering Actually Works: the spam engine that rspamc, pyzor and razor feed into.
• Hardened Roundcube Docker: The Webmail Container That Trusts Nobody: the same cap-dropped, read-only hardening philosophy, applied to webmail.

Pull up a chair. I’ve kept enough servers breathing through enough 3am pages to have firm opinions about HTTP/2, and this one’s a beauty, not because it’s clever in some galaxy-brained way, but because it’s boring. It’s two well-documented behaviours doing exactly what the spec says, multiplied together until your RAM evaporates. The CVSS score is 9.8. Critical. The kind of number that ruins a Tuesday.

And before you ask: yes, this is a different attack from HTTP/2 Rapid Reset. Rapid Reset (CVE-2023-44487) burned CPU by opening and cancelling streams. This one barely touches your CPU. It goes after memory, and it does it by exploiting the gap between two limits your server thought were the same limit. Let me show you.

The HTTP/2 Bomb in one idea: two limits, not one

Every defended HTTP/2 server caps the maximum decoded header size. Send a megabyte of headers and the server says “no thanks” and drops you. This cap exists precisely because of the original 2016 HPACK Bomb (CVE-2016-6581): stuff one enormous value into the compression table, reference it a thousand times, and a tiny request balloons into gigabytes once decompressed. We learned that lesson. We capped total decoded size. Problem solved, we thought.

Here’s the gap, and it’s the whole attack in one sentence: “maximum decoded header size” and “maximum header count” are two different limits, and most servers only enforced the first one. They counted the bytes. They didn’t count the fields. And it turns out the expensive part of a header isn’t the bytes, it’s the per-entry bookkeeping the server allocates around each field. Struct here, pointer there, a little metadata, an entry in a table. Do that ten thousand times with near-empty headers and you’ve spent almost no decoded bytes while forcing the server to allocate a mountain of accounting structures. The size cap never fires, because there’s almost no size. You walked straight under the bar.

Part one: the HPACK indexed-reference bomb (the cheap multiplier)

HTTP/2 compresses headers with HPACK, which keeps a dynamic table, a per-connection dictionary of headers you’ve already sent, so repeats cost one byte instead of the whole string. Lovely for efficiency. The attack seeds the table with one header, then emits thousands of one-byte indexed references to it. Each single wire byte expands into a full header field on the server side, and crucially, into the per-field bookkeeping that goes with it.

How expensive is each byte? Depends on the server’s internals, and the spread is wild. The discoverer’s measured numbers: each wire byte translates to somewhere between 70 and 4,000 bytes of server allocation. nginx, which is fairly lean, sits around 70:1. Apache, which rebuilds merged header strings repeatedly, hits roughly 4,000:1. Same protocol, same attack, two orders of magnitude difference purely from how each codebase chose to store a header. The spec was honest; the implementations each picked their own poison.

The Cookie crumb trick: how to dodge a header-count cap

“Fine,” says the server that did cap header count, smugly. “I limit you to 1,000 fields. Good luck.” And here’s where it gets gloriously petty. RFC 9113 §8.2.3 explicitly permits splitting the Cookie header into one field per crumb. That’s a real, deliberate feature, HTTP/2 lets a client send cookie: a=1, cookie: b=2, cookie: c=3 as separate fields for better compression, and the server is required by the standard to stitch them back together.

Most servers weren’t counting Cookie crumbs against their field limit, because spec-wise they’re “one logical header.” So the attacker pours thousands of empty cookie crumbs down the pipe. Each one is a field. Each field needs bookkeeping. And on Apache specifically, the server rebuilds the merged cookie string repeatedly as crumbs arrive, quadratic-ish string reconstruction over empty data, producing that ~4,000:1 amplification with cookies that contain literally nothing. You’re not even sending data. You’re sending the idea of data, and the server does all the work.

Part two: the window stall, pinning the memory so it never frees

A bomb that detonates and clears up isn’t much of a bomb. You’d allocate, respond, free, and recover. So the second half of the attack makes sure the server can never let go of what it allocated. This is a Slowloris-style hold dressed up in HTTP/2 flow control.

HTTP/2 has per-stream flow control: the receiver advertises a window saying “I can accept this many bytes of your response right now.” The attacker advertises a zero-byte window. The server, obedient, prepares its response, holds it in memory, and waits to send, because the client has said it can’t receive a single byte yet. The response, and every allocation behind it, is now pinned. Then, to stop the server’s idle timeout from giving up and freeing everything, the attacker drips one-byte WINDOW_UPDATE frames, each one resetting the send timeout. Just enough life support to look alive, never enough to drain the buffer. Every allocation stays nailed in place. Multiply across thousands of streams across thousands of connections and you are out of memory in seconds.

The numbers, because they’re genuinely frightening

The discoverer published demo figures, and they’re the kind of thing you read twice. These are single-attacker results, not botnets:

nginx’s relatively modest 70:1 is the upside of a lean codebase, it still falls over, just more slowly. Envoy’s 5,700:1 is what happens when rich internal data structures meet an attack that bills you per structure. Note there’s no botnet column. One machine. One attacker. Tens of gigabytes. That asymmetry is the entire point of a DoS, and this is one of the cleanest ratios ever published against mainstream software.

How to defend it, patch first, then defence in depth

Good news, mostly: the responsible-disclosure process worked, and the fix is conceptually simple once you name the bug. The bug was “we counted bytes, not fields.” The fix is “count fields too.” Here’s the layered defence.

nginx, upgrade to 1.29.8+ and meet max_headers

nginx was told in April 2026 and shipped a fix the next day, a turnaround that deserves a quiet round of applause. Version 1.29.8 adds a new max_headers directive that caps the header field count independently of size, defaulting to 1000. That default is sane for almost everyone; lower it if your app genuinely never sends a thousand headers (it doesn’t).

# nginx 1.29.8+
http2 on;
max_headers 1000;   # new directive: caps header FIELD count, default 1000

Can’t upgrade today? Turn HTTP/2 off until you can:

http2 off;

Apache httpd, mod_http2 v2.0.41

Disclosed to Apache on 27 May 2026; Stefan Eissing committed a fix the same day (these maintainers are not messing around). The fix lives in mod_http2 v2.0.41, available from the standalone mod_http2 releases and in httpd trunk, but at disclosure it was not yet in a 2.4.x release. The patch makes Cookie crumbs count against LimitRequestFields. Until you can deploy it, lowering LimitRequestFieldSize is a partial mitigation, or kill HTTP/2 outright:

# Apache: disable HTTP/2 until mod_http2 2.0.41 is deployed
Protocols http/1.1

IIS, Envoy, Cloudflare Pingora, no patch yet

At disclosure, Microsoft IIS, Envoy, and Cloudflare Pingora had no patch available. If you run these on a public HTTP/2 endpoint, your options are: disable HTTP/2 where you can, or front the server with something that enforces a hard cap on header-field count per request. A reverse proxy or WAF that rejects requests with absurd field counts turns the bomb into a dud before it reaches the vulnerable allocator. This is, incidentally, exactly the architecture we run, a hardened nginx/Angie front edge that can be told “no request needs 9,000 cookie crumbs, drop it.”

The general principle

If you write protocol code: treat “maximum decoded size” and “maximum field count” as separate, independent limits. They are not proxies for each other. Bytes are cheap; bookkeeping is not. Anywhere a client can make you allocate a per-item structure, count the items and cap them, even if each item is empty, especially if each item is empty, because empty is exactly what an attacker will send.

The lesson, because there’s always a lesson

The two ingredients, HPACK reference amplification and flow-control stalling, were public for a decade. Anyone could have read them. The reason nobody combined them isn’t that it was hard; it’s that it lived in the seam between two specialisms, and humans are bad at the seams. We file HPACK under “compression,” flow control under “transport,” and never think to multiply them. An AI model with no such filing system read both codebases end to end and saw one attack where we saw two unrelated footnotes.

That’s the real story here, and it’s coming for every protocol you run. The next decade of vulnerabilities won’t all be novel bugs. A lot of them will be old, documented, individually-harmless behaviours that nobody bothered to compose, dragged into the light by something that reads faster than you and forgets nothing. The defence is the same as it’s always been, count what costs you, cap what a stranger can make you do, and assume the seams between your subsystems are exactly where the next bomb is hiding. Go check your nginx version. I’ll wait.

Frequently asked questions

Related reading

• What Is the BREACH Attack? How It Works and How to Stop It: another attack that weaponises a normal HTTP feature (compression). Same “the spec was honest, the threat model wasn’t” flavour.
• How to Install ModSecurity and OWASP CRS on NGINX: put a real WAF in front of the endpoints that need a hard header-count cap.
• Docker Hardening for Self-Hosters: Rootless, Read-Only, Cap-Drop, Distroless: memory limits and cap-drop are exactly the blast-radius control that turns an OOM into a contained restart.
• NGINX Modules, Optimized & Extended: the hardened nginx builds, packaged for Debian and Ubuntu, where fixes like 1.29.8 land fast.

I’ve spent enough years watching default container images get owned to develop a particular kind of contempt for the phrase “it works out of the box.” Of course it works out of the box. So does a bank vault with the door left open. The question was never whether it works. The question is what happens when someone who isn’t you starts poking it. And the honest answer, for most webmail Docker images on the registry, is: nothing good, very quickly, and you’ll find out from your logs three weeks later, assuming you read your logs, which, let’s be honest, you don’t.

So we built eilandert/roundcube: a hardened Roundcube Docker image that runs as a non-existent user, can’t change the ownership of a single file, treats its own root filesystem as carved in granite, and has a web application firewall bolted to the front that assumes, correctly, that the internet is full of people who want to ruin your day. This is the tour. Bring coffee.

What a hardened Roundcube Docker image actually is (and why you’d containerise it)

Roundcube is webmail. It’s the thing that turns a raw IMAP mailbox into a browser interface that normal humans can use without learning mutt keybindings or developing a thousand-yard stare. You point it at an IMAP server for reading mail and an SMTP server for sending it, give it a database to remember contacts and preferences, and it hands your users a clean, fast, plugin-extensible inbox in any browser. It’s PHP. It’s been around since 2008. It is, by webmail standards, genuinely lovely software.

Here’s the thing the marketing pages won’t tell you: Roundcube is a PHP application that sits directly between the public internet and your users’ email. Read that sentence again. Every credential, every private message, every password-reset link in someone’s inbox is on the other side of this login form. That makes it one of the highest-value targets you can self-host. A compromised blog is embarrassing. A compromised webmail is a credential-harvesting machine that hands an attacker the keys to every other account those users own, because where do you think password reset emails go?

Containerizing it is the right call. You get a reproducible, version-pinned, throwaway runtime that you can rebuild from scratch in ninety seconds and that doesn’t leave PHP extensions rotting on your host for the next decade. But, and this is the entire point of this post, a container is not a security boundary by default. Out of the box, Docker gives a process inside the container root, a writable filesystem, and a frankly alarming pile of capabilities. If your “hardened” webmail image is really just upstream Roundcube with a Dockerfile that says USER root and calls it a day, you have containerized the blast radius, not contained it.

The Luser’s Container vs. Ours: Running as Nobody

Let’s start with the single most important word in this entire image: unprivileged. The container runs as UID 10001, a system user called roundcube that owns the application code and absolutely nothing else of value. PID 1 inside the container, the very first process, is not root. The Angie web server master, the PHP-FPM master, every worker they spawn, all of them are this nobody user.

Why does this matter so much? Because the classic container escape story goes: attacker gets code execution inside the container (say, through a PHP bug), and then uses the fact that they’re root inside it to chew through a kernel vulnerability or a misconfigured mount and land as root on your host. If the process was never root to begin with, that entire escalation chain loses its first link. The attacker who pops our PHP worker finds themselves as UID 10001, who owns some read-only PHP files and has the system privileges of a particularly disappointing houseplant.

To make this work, the whole identity model is collapsed to one user. There’s no root master “dropping” to a worker user via setuid(), because a non-root master can’t setuid, that needs CAP_SETUID, which (spoiler) we don’t have. Instead, both Angie and PHP-FPM inherit the container’s identity from the start. The Angie config has no user directive. The PHP-FPM pool has its user and group lines commented out. Set them, and a non-root master throws an error and refuses to boot. We learned that the polite way, by reading the error message, which is more than I can say for most people.

And here’s the consequence that trips up everyone the first time: the container cannot chown anything. Not won’t, can’t. With all capabilities dropped, there’s no CAP_CHOWN to change file ownership. So every writable mount has to already be owned by UID 10001 on the host before the container starts. Named Docker volumes inherit this automatically from the image’s directory ownership. Bind mounts you pre-chown yourself: sudo chown -R 10001:10001 ./roundcube/config. Forget to, and the container fails to boot with a Permission denied, which is annoying for about thirty seconds and then deeply reassuring, because it means the container genuinely has no power to fix it on its own. That’s the whole idea.

Dropping Every Capability and Nailing the Filesystem Shut

Linux capabilities are the granular pieces that root‘s god-mode used to be one indivisible blob. Bind to a low port? CAP_NET_BIND_SERVICE. Change file ownership? CAP_CHOWN. Override file permission checks entirely? CAP_DAC_OVERRIDE, the capability that says “permissions are a suggestion.” Default Docker hands a container a pile of these for no reason other than tradition. Our compose file says cap_drop: [ALL] and adds back exactly zero. The container runs with an empty capability set. CapEff is 0000000000000000. It has nothing.

“But how does it bind a port with no CAP_NET_BIND_SERVICE?” Excellent question, you’re paying attention. It doesn’t bind a privileged one. Angie listens on :8080, which is above 1024 and therefore bindable by any user without special powers. You terminate TLS at an upstream reverse proxy and point it at :8080. The container never needs to touch a privileged port, so it never needs the capability to, so we can take it away. This is the recurring theme: every capability we don’t need, we design out, then drop. You can read the full philosophy in our Docker hardening guide for self-hosters, which is the ten-flag checklist this image is built on.

Then we glue the floor down. read_only: true mounts the entire root filesystem immutable. An attacker who gets a write primitive has nowhere to write a webshell, nowhere to drop a cron payload, nowhere to modify the application code that’s about to execute. The only writable surfaces are explicit, minimal, and isolated: a tmpfs at /tmp (sockets, the PID file, Angie’s scratch temp dirs, Roundcube’s attachment staging) owned by UID 10001, and a config volume holding exactly one generated file. That’s it. Everything else is granite.

We finish the container layer with two more flags that cost nothing and matter enormously. no-new-privileges: true sets the kernel bit that makes setuid binaries and similar escalation tricks no-ops, even if some leftover setuid binary existed (we strip the bits at build time anyway, belt and braces), it could not be used to gain privilege. And apparmor=docker-default loads the host’s AppArmor profile, a mandatory-access-control layer that constrains what syscalls and paths the process can touch regardless of file permissions. AppArmor is enforced by the host kernel, not bundled in the image, so your Docker host needs it, most do by default on Debian and Ubuntu.

Snuffleupagus: The PHP Bodyguard That Doesn’t Trust PHP

PHP is a wonderful language to attack. Decades of footguns, a function for every dangerous thing you could possibly want to do, and a community-wide habit of eval()-ing things that should never be eval’d. So we don’t trust it. We run Snuffleupagus, a PHP hardening extension, conceptually the spiritual successor to Suhosin, with a strict, source-audited rulebook tailored to Roundcube.

Snuffleupagus operates at the engine level. It can virtually patch known-vulnerable function behaviors, kill dangerous functions entirely, enforce that uploaded files can never be executed, lock cookies to secure flags from inside the interpreter, and detect when a function is being called from a context it has no business being called from. The point is defense at a layer the application code can’t override. An ini_set() in some compromised plugin can’t undo a Snuffleupagus rule. It’s a bodyguard who reports to the building, not to the guest.

Backing it up at the PHP-FPM pool level is a layer of php_admin_value hardening, the admin prefix meaning userland ini_set() cannot override these. open_basedir confines PHP’s filesystem access to the application directory plus its few writable runtime paths; PHP literally cannot fopen() outside that jail, so the classic “read /etc/passwd via path traversal” trick returns nothing. disable_functions nukes the obvious subprocess and reconnaissance surface, exec, shell_exec, system, proc_open, passthru, pcntl_exec, php_uname, the lot, so even a perfect remote-code-execution bug finds the gun cabinet welded shut.

And the session cookies get the full treatment: secure (never sent over plaintext HTTP), httponly (invisible to JavaScript, so an XSS can’t steal the session), and samesite=Strict (not sent on cross-site requests, which guts CSRF). Session IDs are 64 characters of strict-mode entropy. None of this is exotic. All of it is the stuff that “works out of the box” images can’t be bothered to set, because the box ships with the defaults PHP picked in 2009.

The Angie WAF: Assuming Every Request Is an Attack

The web server is Angie (the nginx fork with the saner config and the better defaults), and we’ve turned its front door into a checkpoint. Not a friendly one. The kind that assumes you’re guilty and makes you prove otherwise.

First, gzip is off. Entirely. This is not a performance oversight, it’s deliberate, and it stops the BREACH attack. BREACH is a compression side-channel: if you compress a response that contains both a secret (like a CSRF token) and attacker-influenced content, the size of the compressed output leaks information about the secret, one byte at a time. Roundcube’s HTML is stuffed with session-bound CSRF tokens. Compressing it dynamically would hand an attacker a BREACH oracle. So we don’t. The static assets are small and cacheable; the bandwidth cost of leaving gzip off is trivial; the security win is real.

Second, the server actually knows who it’s talking to. Sitting behind a reverse proxy, a naive backend sees every request as coming from the proxy’s IP, which makes per-client rate limiting useless and turns your failed-login tracking into a single bucket for the entire internet. We configure real_ip to trust the private proxy ranges and read the true client address from X-Forwarded-For. Now the controls below can actually distinguish one attacker from ten thousand legitimate users behind the same proxy.

Third, the scanner gate. Empty user-agent? return 444, Angie’s special “close the connection without so much as a response” code. User-agent matching nikto, sqlmap, nmap, masscan, nuclei, wpscan, and the rest of the script-kiddie starter pack? Same treatment. Yes, a competent attacker will change their user-agent. But the overwhelming majority of the traffic hammering any public endpoint is automated garbage that doesn’t bother, and 444-ing it costs us nothing while denying them the satisfaction of even a 403. It’s the digital equivalent of not buzzing the door.

Fourth, login brute-force throttling. Roundcube funnels its login through /index.php?_task=login&_action=login, but every dynamic page hits index.php too, so a naive rate limit would throttle normal browsing into oblivion. The trick: a request map keys the rate-limit zone on the real client IP only for the login action, and on an empty string otherwise. An empty key isn’t counted. So the throttle, 12 requests per minute, with a small burst to absorb a human fat-fingering their password, applies to login attempts and login attempts alone. Brute-force a password here and you get a 429 after twelve tries a minute, keyed to your actual address, while the user next to you behind the same corporate proxy browses unbothered.

And finally the response headers, the cheap stuff everyone forgets: a Content-Security-Policy that pins script, style, image, and connection sources to self (with the unsafe-inline concessions Roundcube’s skin genuinely requires, because it has no nonce support, we’re honest about that rather than shipping a CSP that breaks the UI and gets disabled), frame-ancestors 'none' to kill clickjacking, object-src 'none', and a HSTS header with a two-year max-age, includeSubDomains, and preload eligibility, originating from the app so it survives the proxy. None of it is glamorous. All of it is the difference between “we thought about this” and “we shipped the defaults.”

Defense in Depth, or: Why Bother With All Of It?

A reasonable person, not you, you’re reading a 3000-word post about webmail hardening, but a reasonable person, might ask why we need all of this. Surely one good layer is enough? Surely if the app is patched, the rest is paranoia?

No. The entire premise of defense in depth is that any single layer will fail, because layers are written by humans and humans are a catastrophe. The WAF might miss a novel payload. Snuffleupagus might not have a rule for tomorrow’s CVE. The app might ship a bug between your last pull and your next one. So you stack independent controls such that the attacker has to defeat all of them, in sequence, to get anywhere, and each one buys you time, noise in the logs, and a decent chance they give up and go bother someone with a softer target.

Walk the kill chain. An attacker finds a fresh Roundcube RCE. The WAF’s scanner gate already dropped their recon traffic, so they had to work harder to even map the surface. They land code execution, but they’re UID 10001, not root, so no privilege escalation freebie. They try to write a webshell, read-only filesystem, nowhere to put it. They try to spawn a reverse shell, disable_functions ate exec and friends, and Snuffleupagus is watching the rest. They try to read secrets off disk, open_basedir jails them to the app directory. They try to escalate through a kernel bug, no capabilities, no-new-privileges set, AppArmor constraining the syscall surface. At every single step, a layer they didn’t expect says no. That’s not paranoia. That’s just doing the job.

It’s the same philosophy that runs through everything we self-host, from our self-hosted Vaultwarden setup to the ModSecurity and OWASP CRS stack we put in front of higher-risk apps. Layers. Always layers. The attacker only has to be right once; you have to be wrong everywhere, all at once, for it to matter, so make “everywhere, all at once” as expensive as you possibly can.

What’s In The Box: Plugins and Skins

Hardening is the point, but nobody wants webmail that’s a security exhibit and nothing else. So the image ships a curated pile of plugins and skins, pre-installed, loaded only when you ask for them via ROUNDCUBEMAIL_PLUGINS. Nothing runs that you didn’t list, minimal attack surface by default, opt in to what you need.

The bundled plugins: contextmenu and contextmenu_folder (right-click menus on messages and folders), swipe (touch gestures), show_folder_size, quota (IMAP quota display), persistent_login (“keep me logged in”), advanced_search, account_details, message_highlight (colour rules), authres (shows SPF/DKIM/DMARC results so you can spot forgeries), thunderbird_labels, responses (canned replies), easy_unsubscribe (one-click List-Unsubscribe), rcguard (reCAPTCHA after failed logins, another brute-force layer), kolab_2fa (two-factor: TOTP, Yubikey, U2F), and carddav (address-book sync). The 2FA support libraries, endroid/qr-code, spomky-labs/otphp, enygma/yubikey, come along for the ride. Roundcube’s own core plugins (archive, zipdownload, managesieve, password, newmail_notifier, new_user_dialog) are enabled out of the gate.

The bundled skins (pick one with ROUNDCUBEMAIL_SKIN, default elastic): elastic (the responsive default), elastic4mobile (mobile-tuned), elastic-dark (dark mode), elastic2025 (a refreshed look), plus two we built ourselves, gmail and outlook365, look-alikes for the people migrating off Big Mail who want the muscle memory intact. And for the nostalgic: larry and classic, the old Roundcube skins, still here, still working.

Running It Yourself

Pull eilandert/roundcube:latest, give it an external MariaDB or PostgreSQL (there’s no SQLite fallback, on purpose, webmail is not a toy), point it at your IMAP and SMTP servers, and front it with a TLS-terminating reverse proxy targeting :8080. The entrypoint generates the Roundcube config from environment variables on every start, ensures the database schema, and starts the stack, all as UID 10001, chowning nothing, because it can’t.

The one thing you cannot skip: pre-own the writable mounts. sudo chown -R 10001:10001 on any bind mount, or use named volumes that inherit it automatically. If the container boots, you got it right. If it dies screaming Permission denied, you didn’t, and that’s the read-only, cap-dropped, unprivileged design working exactly as intended, refusing to paper over your mistake with privileges it doesn’t have. The full source, the Dockerfile, the Angie config, and the PHP-FPM pool all live at github.com/eilandert/dockerized. Read it. Audit it. That’s the point of shipping it in the open.

Default webmail containers trust the user, trust the network, trust PHP, and trust that nobody will ever be rude enough to attack them. Ours trusts nobody, and sleeps fine.

Frequently Asked Questions

Related Reading

• Docker Hardening for Self-Hosters: the ten-flag checklist (rootless, read-only, cap-drop, distroless) this image is built on.
• What Is the BREACH Attack?: why we turn gzip off on dynamic HTML, explained from first principles.
• Self-Hosted Vaultwarden: the same unprivileged, minimal-container philosophy applied to your password vault.
• Install ModSecurity and OWASP CRS on NGINX: adding a full rule-based WAF in front of higher-risk apps.

This is what happens when your mail server user management is “open a MySQL client and hope.” ViMbAdmin is the alternative, a web panel that sits between your caffeine-addled hands and the database that runs your virtual mail. Our modernised fork brings it up to PHP 8.5, adds a full JSON-RPC API, TOTP, brute-force protection, and a security posture that assumes, correctly, that the entire internet is trying to get in. Fork is here: github.com/eilandert/ViMbAdmin.

👉 Want to poke at it first? A live demo runs at vimbadmin.myguard.nl — the real panel, with password and 2FA changes locked and outgoing mail no-op’d for the demo account. Log in, click around, break nothing.

What ViMbAdmin actually is

Postfix and Dovecot do not care how the rows get into your database. They read virtual_mailbox_maps, they hash a password, they deliver mail, they go back to sleep. The database is the contract. How you maintain that contract is left, with magnificent Unix indifference, as an exercise for the reader.

Most people solve this one of three ways:

1. Raw SQL, forever, on three hours’ sleep, one typo away from dropping the wrong domain.
2. A full mail appliance that installs 47 things you didn’t ask for, writes its own Postfix config, and breaks every time you touch anything.
3. ViMbAdmin.

ViMbAdmin is a CRUD app over three concepts: domains (@example.com, with quotas and mailbox limits), mailboxes (actual accounts with bcrypt-hashed passwords, maildirs, quotas), and aliases (the forwards, sales@ → wherever, postmaster@ → the person whose job it is to read bounces). It writes to the shared database. Postfix and Dovecot pick up the changes on their next lookup. That’s the whole transaction.

It does not configure Postfix. It does not install Dovecot. It does not filter spam, for that you want Rspamd. It is a component, deliberately narrow, which is exactly why it can be audited and trusted. Tools that try to do everything are the tools that have a buffer overflow in the “we didn’t think anyone would use this” codepath.

Mailbox passwords are hashed natively in PHP into exactly the format Dovecot stores — no doveadm pw binary, no shell-out, no network round-trip. It produces the crypt-family schemes PHP and Dovecot share, strongest first: ARGON2ID (memory-hard, Dovecot’s recommended modern scheme — set it if you hash out-of-band), then BLF-CRYPT (bcrypt $2y$, the recommended native default), then SHA512-CRYPT, then SHA256-CRYPT. If you’ve ever spent an evening debugging why your hand-rolled {SHA512-CRYPT} prefix was subtly wrong, you know what this is worth.

The history: perfectly good software, abandoned mid-sentence

ViMbAdmin was written by Open Solutions, an Irish shop, around 2010. Zend Framework 1, Doctrine ORM, Smarty, a perfectly sensible stack for the era. Then, as happens to a great deal of genuinely useful software, the commits slowed. Then stopped. The last meaningful upstream release predates several PHP versions that have since been born, matured, and declared end-of-life.

Run the stock code on PHP 8.x and you get a wall of deprecation notices, a couple of fatals, and the special kind of silence where a form should have rendered. It didn’t die so much as sit down, mid-sentence, and stop talking.

We needed it on PHP 8.5 on a hardened production stack. So we fixed it. Then, because leaving a five-year-dormant admin panel on the internet with no security review is how you become a cautionary tale, we kept going.

What we actually changed (the itemised version, not the press release)

PHP 8.5, Smarty 5, Doctrine ORM 3

The framework internals got a full transplant. Smarty 4 → 5: the templating layer changed under us in three distinct ways. It removed the public property API the old OSS_View_Smarty bridge poked at. It dropped bare PHP function calls inside {if} expressions. And, the landmine, its backward-compat plugin loader makes getPluginsDir() return an empty array, so the cloned view that Zend’s form-partial renderer uses silently lost every custom plugin. Forms rendered as blank space. No error, no warning, just nothing. We now track plugin directories manually and re-register them on clone.

Doctrine ORM 2.8 → 3.x (currently orm 3.6 / dbal 4 / persistence 4) renamed half the query API along the way. CLI bootstrap, fetchAll() calls, the works. Every function f(Type $x = null) implicit-nullable across the entity and proxy trees got the ?Type treatment, because Zend_Session promotes that particular deprecation to a fatal during session start, and nothing tanks user trust in a mail admin panel like a white screen at login. The jump to ORM 3 specifically needed native lazy-loading proxies (enableNativeLazyObjects — Symfony 8 retired the old var-exporter ghosts), PSR-6 caches in place of the deleted DoctrineProvider, an XSD-clean rewrite of the XML mappings, and a small object-type shim DBAL 4 dropped. Cache layer: doctrine/cache 2.x deleted its concrete providers, so the metadata/query cache now wraps a Symfony Cache PSR-6 pool. Without a persistent backend Doctrine re-parses entity mappings on every single request. With APCu it parses them once. The Docker image leaves doctrine2cache.type = auto, which picks APCu when the extension is present — for a single container that beats Redis, no socket, no hop. OPcache with validate_timestamps=0 and a preload script round it out.

Security: the actual list, not “we hardened it”

The stock app had no CSRF protection. None. Every form, every destructive link, wide open. We added a per-session token to the base form class, every form inherits it, Zend’s isValid() checks it for free, then guarded every destructive GET link (purge, delete, cancel, restore) with an explicit token check. Forge a request without the token: 403, redirect, no mailbox deleted.

Smarty was running with output escaping off. Every {$variable} was a stored-XSS waiting room. We flipped setEscapeHtml(true) globally and marked the genuinely-HTML outputs as nofilter. A description field containing <script>alert(1)</script> now renders as inert text. We tested that payload. It does nothing, which is the point.

SQL injection: Doctrine ORM with parameterised queries throughout, plus we deleted four unreferenced “OSS API” integration classes that were carrying actual SQL concatenation (one with a live injection). ~1,600 lines removed. Dead code in an admin panel is attack surface.

Command injection: every shell-out (doveadm, archive tar/bzip2/du) is escapeshellarg()‘d. Deserialisation: unserialize() of archive blobs is restricted with ['allowed_classes' => false]. Tokens and backup codes use random_int(), the old str_shuffle/mt_rand was replaced. CSRF: covered above. Every session ID is regenerated on login, and again after the 2FA step.

TOTP two-factor auth

Opt-in per admin at /admin/two-factor. Scan QR, confirm a code, save the one-time backup codes (they’re shown once, they work once each, write them down, or find out the hard way). The TOTP secret is stored encrypted at rest with libsodium, keyed off securitysalt. A database read yields nothing usable.

The lockout-yourself scenario: two escape hatches, no SQL required.

# phone dead, authenticator gone — CLI reset:
./bin/vimbtool.php -a admin.cli-reset-totp --username=you@example.com
./bin/vimbtool.php -a admin.cli-reset-totp --all   # bad day

# or, applied at next login:
; in application.ini:
twofactor.force_disable = "you@example.com"   ; or "*"

Brute-force protection

Per-source-IP attempt counter, configurable lockout window. A fully successful login (password + 2FA, both) clears the counter. Configure in application.ini:

bruteforce.enabled      = 1
bruteforce.max_attempts = 5
bruteforce.window       = 900    ; seconds counter accumulates over
bruteforce.lockout      = 900    ; seconds locked out
bruteforce.whitelist[]  = "127.0.0.1"
bruteforce.whitelist[]  = "10.0.0.0/8"

If you’re behind a reverse proxy, see the trusted-proxy section below, the limiter needs the actual client IP, and there’s a right way and a very wrong way to get it.

Defence in depth: Snuffleupagus, ModSecurity, hardened configs

Application-layer fixes are necessary. They’re not sufficient. The fork ships three more layers:

• Snuffleupagus ruleset (contrib/snuffleupagus/vimbadmin-strict.list): code-derived, not copy-pasted from a blog post. Every ban is checked against a scan of what the app and its vendor tree actually call. It bans dangerous PHP functions the app never touches, allow-scopes the few it does, and blocks RFI/LFI wrappers, eval/base64_decode webshell pipes, mail-header injection, world-writable chmod, writing PHP-loadable files, and insecure cURL. The latest pass dropped roughly thirty more — a webshell’s favourite egress and RCE channels (imap_open, ftp_connect, the ssh2_* family, pfsockopen, expect_*), runtime code-redefinition (runkit/uopz), filesystem-ownership calls, and host-fingerprinting functions — each verified to have zero real call-sites first, so nothing legitimate breaks. Note: do not stack native disable_functions with Snuffleupagus, they conflict and the worker SIGSEGVs. Ask how we know.
• Hardened PHP-FPM pool (contrib/php-fpm/vimbadmin.conf): open_basedir, empty native disable_functions (SP owns policy), strict session-cookie flags, security.limit_extensions=.php, sane resource limits.
• Hardened Angie/nginx vhost (contrib/angie/vimbadmin.conf): positive security gate: only known HTTP methods, the exact route map (controllers + ZF1 param URLs), and the app’s known argument names reach PHP. Scanner traffic, empty user-agents, and the eternal /.env//wp-login.php probe loop die at the edge. Plus strict CSP, security headers, BREACH mitigation (no compression on dynamic HTML), and a rate-limited login endpoint. Optional add-on: the ModSecurity CRS plugin for payload-signature scanning on top.

Quick start

Docker (recommended: fastest path to a running panel)

Bring a MariaDB/MySQL database. The image bundles the app, PHP-FPM, and the web server, pre-wired. First boot generates secrets and sets up the schema. Config lives in a mountable volume, edit application.ini without rebuilding, no files clobbered. The image is on Docker Hub at hub.docker.com/r/eilandert/vimbadmin (eilandert/vimbadmin:latest), built from the dockerized recipe; the app source is the ViMbAdmin fork on GitHub.

services:
  db:
    image: mariadb:lts
    environment:
      MARIADB_ROOT_PASSWORD: actually-change-this
      MARIADB_DATABASE: vimbadmin
      MARIADB_USER: vimbadmin
      MARIADB_PASSWORD: also-change-this

  vimbadmin:
    image: eilandert/vimbadmin:latest
    depends_on: [db]
    ports:
      - "8080:80"
    environment:
      TZ: Europe/Amsterdam

docker compose up -d
# wait for MariaDB's first-boot, then browse to http://localhost:8080/

Put it behind TLS in production. Behind the hardened vhost from contrib/ if you can. The point of shipping deployment configs is that you don’t have to invent them under pressure at 23:00.

From source

PHP 8.4.1+ with pdo_mysql, mbstring, intl, gettext, dom, ctype, iconv, sodium (2FA encryption). apcu optional but don’t skip it.

git clone https://github.com/eilandert/ViMbAdmin.git
cd ViMbAdmin
composer install --no-dev
cp application/configs/application.ini.dist application/configs/application.ini
# edit application.ini: point resources.doctrine2.connection.options.* at your DB
./bin/doctrine-cli.php orm:schema-tool:create

That last command is the modernised CLI. The stock one called a Doctrine 2.8 API that no longer exists (the fork is on ORM 3 now). PHP 8.4.1 is the dependency-tree floor.

First run: claim the throne before someone else does

On first launch ViMbAdmin detects no administrators exist and routes you to a setup page. This is the one window where the panel is briefly unauthenticated. Do it immediately, on a network you trust, then never think about it again.

The setup page generates a security salt, use the one it gives you. Then it asks for your first super-admin’s credentials. The username is an email address. Not the word “admin.” Not “root.” An actual you@yourdomain.com. The field is labelled “Email.” Read the label. This trips up more people than you’d believe, and none of them believe it could trip them up until it does.

Pick a real password. It’s bcrypt-hashed and constant-time-compared on every login. The strength is entirely on you. The super-admin can see and touch everything. Treat the credentials accordingly.

Day-to-day: domain, mailbox, alias, in that order

The order matters because the foreign keys matter.

1. Domains → Add. Set the limits (max mailboxes, max aliases, default quota), decide backup MX status. ViMbAdmin writes the row. Postfix will now accept mail for the domain: assuming your virtual_mailbox_domains is actually pointed at this database. The panel maintains the data; it can’t make Postfix care about a table you never configured it to read. That part is on you.
2. Mailboxes → Add. Local part, password, quota. ViMbAdmin hashes the password natively in your configured scheme (ARGON2ID / BLF-CRYPT / SHA512-CRYPT — no doveadm pw binary involved), computes maildir path, stores it. User can now authenticate against Dovecot. If you enabled the welcome-email feature, it tells them: which beats texting them a plaintext password, a practice that should be punishable by having to read your own sent folder.
3. Aliases → Add. Address → comma-separated goto list. Build your postmaster@ (RFC 5321 requires it, you will forget until a remote server complains), your role addresses, your distribution lists.

Every action is logged, validated, and CSRF-protected. The delete button on a mailbox carries a token; a malicious page can’t trick your browser into purging an account behind your back.

No more scripts: archive, autoprune and quotas are all Dovecot-native

This is the part that changed the most, and it’s the part that makes the panel genuinely pleasant to run. The original ViMbAdmin leaned on a pile of helper scripts and cron jobs that had to live on the mail host, where the maildirs are: one to tar up an archive, one to scan every maildir for its size, one to actually delete files off disk. They needed shell access to the mail filesystem, they needed to be kept in sync with the panel, and if you forgot one, features silently didn’t work.

All of that is gone. The panel now talks to Dovecot over its doveadm HTTP API — a REST endpoint — and never touches the mail filesystem itself. No tarballs, no du, no shared mount, no scripts to deploy on the mail host. The web request just writes a small job to a database queue, and a background runner carries it out against Dovecot. There is one moving part instead of five, and it’s a network call to an API, not a shell command on someone else’s server.

Delete → archive → autoprune

Deleting a mailbox is no longer a destructive single click you regret at 02:00. When you delete (or explicitly archive) a mailbox, the runner asks Dovecot to doveadm backup the whole store into a zstd-compressed maildir under your backup path, and only then removes the live account. The backup shows up on the new Archives tab: when it was made, whether the account still exists, and its autoprune state. A deletion’s backup is flagged for autoprune and is cleaned up automatically after a configurable number of days (default 90; set it to 0 if you want delete to mean delete now, no backup). Changed your mind inside the window? Restore recreates the mailbox — original password hash and all — and doveadm syncs the mail back from the backup. Future-you, the one not reconstructing a fat-fingered deletion from a three-day-old dump, is grateful.

The Maintenance tab

There’s a new Maintenance tab that surfaces all the housekeeping in one place instead of hiding it in cron files: app and schema version, the last queue-run and prune markers, inactive-domain stats, and one-click buttons to update the database schema, run autoprune now (clear expired backups), or delete all autoprune backups. The same actions are available headless for a cron (maintenance.prune-expired) if you’d rather automate them — but you no longer have to.

Quotas update themselves, in real time

Two things people conflate: the limit (how big a mailbox is allowed to get) and the usage (how full it is right now). ViMbAdmin owns the limit — you set it in the GUI. Dovecot owns the usage, and it now reports it back live via its quota-clone plugin, which writes each mailbox’s current byte count straight into a table the panel reads. No nightly maildir-scan cron, no stale numbers — the usage bar you see is what Dovecot measured on the last delivery. The old size-scanning script that used to crawl every maildir overnight is simply retired.

MCP adapter: JSON-RPC API for when clicking is beneath you

Off by default. Enable with mcp.enabled = 1 in application.ini. This is a JSON-RPC 2.0 API at /mcp that lets an agent, a script, or a CI pipeline read and manage the mailbox database without a human in the loop. The full method set:

Auth is bearer-only, no session, no cookie. Only the SHA-256 hash of each token is stored; a database read yields nothing usable. Tokens are scoped (read or read write), per-token IP/CIDR allowlisted, expirable, and revocable from the CLI without touching the web panel:

# read-only token — printed once, store it now
./bin/vimbtool.php -a mcp.cli-token-generate --name=agent1 --scope="read"

# write-scoped, IP-locked, 90-day expiry
./bin/vimbtool.php -a mcp.cli-token-generate --name=provisioner \
    --scope="read write" --ip="10.0.0.5" --days=90

./bin/vimbtool.php -a mcp.cli-token-list
./bin/vimbtool.php -a mcp.cli-token-revoke --name=agent1

The vhost should enforce an IP allowlist in front of /mcp as primary network defence (the contrib/angie/vimbadmin.conf has the block). Bearer is the application layer on top. Revoked names can be reused, the CLI drops the old row rather than refusing, so token rotation doesn’t require inventing new names.

Real client IP behind a proxy: do it right or your brute-force protection is a lie

If your reverse proxy sits in front of ViMbAdmin and you haven’t configured trusted-proxy handling, your brute-force limiter sees the proxy’s IP address, not the attacker’s. It will either lock out nobody (if the proxy is whitelisted) or lock out your entire office (if the proxy isn’t). Both outcomes are bad. The MCP per-token IP allowlist has the same problem.

Controlled by trustedproxy.mode in application.ini:

; auto (default) — trust X-Forwarded-For only when REMOTE_ADDR is private/loopback
trustedproxy.mode = "auto"

; on — trust X-Forwarded-For only from the listed proxy CIDRs
;trustedproxy.mode = "on"
;trustedproxy.proxies[] = "10.0.0.0/8"
;trustedproxy.proxies[] = "172.16.0.0/12"

; off — ignore X-Forwarded-For, always use raw REMOTE_ADDR
;trustedproxy.mode = "off"

• auto (default): trusts X-Forwarded-For only when REMOTE_ADDR is a private or loopback address. Covers the standard “proxy on the same host or LAN” setup with zero configuration. A public REMOTE_ADDR bypasses the header entirely.
• on: trust X-Forwarded-For from the CIDRs you list. Use when your proxy is on a public IP or a separate network segment.
• off: always use raw REMOTE_ADDR. Use when you handle IP rewriting at the web server layer instead (Angie/nginx real_ip module, there’s a commented example in contrib/angie/vimbadmin.conf).

The client is taken as the right-most address in the X-Forwarded-For chain that isn’t a trusted proxy. A client can’t spoof it by prepending extra IPs to the header, the leftmost entries are attacker-controlled, the rightmost is what your proxy saw.

Upgrading and schema migrations

Pulling a new version may add columns, indexes, or tables. Two paths:

# Option A: Doctrine reconciles DB against entity mappings
./bin/doctrine-cli.php orm:schema-tool:update --dump-sql   # see what it wants to do
./bin/doctrine-cli.php orm:schema-tool:update --force      # do it

# Option B: targeted migration from contrib/migrations/
mysql -u<user> -p <database> < contrib/migrations/2026-06-mailbox-username-unique.sql

contrib/migrations/ holds idempotent SQL for changes that warrant a named file and a comment. Current one: UNIQUE index on mailbox.username. Postfix and Dovecot query that column on every delivery and login. Without the index they full-scan the mailbox table every time. Fresh installs have it; DBs created from older dumps don’t. Before applying, check for duplicates (yes, they happen):

SELECT username, COUNT(*) c FROM mailbox GROUP BY username HAVING c > 1;

schema-tool:update is additive (adds, doesn’t drop). The migration files do exactly what they say. Back up the database first regardless. This is not optional advice.

Where it fits in a real mail stack

The components and their responsibilities: Postfix handles SMTP. Dovecot handles IMAP/POP. Rspamd handles spam scoring before any of that. A web server fronts everything. ViMbAdmin keeps the shared user database coherent. That’s it. The deliberate narrowness is a feature, a tool with one job can be audited, hardened, and trusted in a way a sprawling appliance never can.

One boundary to be clear about: ViMbAdmin only writes to the database. It never touches maildirs. The “archive” and “delete” buttons queue a row; a background runner does the real work against Dovecot over its HTTP API (doveadm backup to a zstd-compressed maildir, then doveadm sync to restore) — no tarballs, no shell tools, no shared filesystem with the mail host. In the Docker image that runner is the supervised queue-runner from earlier, ticking every five minutes with nothing to install. On bare metal you add a cron calling queue.cli-run; the fork ships examples in contrib/cron/ with their requirements documented inline. Mailbox usage is fed live by Dovecot’s quota-clone plugin, so there’s no nightly maildir-scan job any more either.

If you’re running this stack on Debian or Ubuntu, the rest of our work slots in beside it: hardened nginx/Angie packages with HTTP/3, daily-rebuilt Docker images, and a general operating principle that default configs are a starting point for hardening, not a destination. ViMbAdmin, properly deployed, is the mail-admin-shaped piece of that.

Stop editing your mailbox table by hand. Future you, the one not reconstructing a dropped domain at 02:00 from a backup that’s three days old, will not thank you, because future you will be asleep.

Frequently asked questions

Related reading

• Rspamd Explained: How Modern Spam Filtering Actually Works: the spam-filtering piece that sits beside ViMbAdmin in a real Postfix/Dovecot stack.
• What Is the BREACH Attack?: why we disable compression on dynamic HTML, from first principles.
• Docker Hardening for Self-Hosters: the ten-flag checklist for running the ViMbAdmin container properly.
• Angie and NGINX Docker Images: daily-rebuilt, fully-moduled web-server images to front the panel.
• ViMbAdmin on Docker Hub: pull eilandert/vimbadmin:latest — the self-supervising, read-only, unprivileged image this article describes.

None of this is specific to Debian packaging, these five tools speed up any C/C++ build: a kernel compile, an autotools project, a CMake tree, a Yocto image, a CI pipeline. The examples below are generic shell. Wire them into whatever build system you already use.

This is the whole shambam. Five tools, what each one actually does, how to plug them into your workflow, what they cost, and what they break. By the end you’ll know which ones to switch on tomorrow, which one to think twice about, and the order to enable them in so you can measure the wins individually instead of crossing your fingers and hoping.

Why your build is slow: Debian package build optimization starts here

Open htop during a real package build. You’ll see gcc use one core, hit 100%, then drop to zero for two seconds while dpkg unpacks a build-dep. Then one core again. Then ld single-threaded for forty seconds at the link step. Then make install writing five thousand files to disk one fsync at a time. Then the whole thing again for the next binary package in the same source.

The CPU isn’t the bottleneck. Almost nothing in a typical Debian build saturates a modern processor. The bottlenecks, in rough order of pain, are:

• fsync storms from dpkg, apt, ldconfig, and friends installing build-deps and writing the final .deb
• Single-threaded linking with ld or even gold on anything with a lot of static libraries (looking at you, NGINX with twenty modules)
• Pointless recompilation of files whose source bytes are identical to last time
• One-machine parallelism: your -j$(nproc) stops at the box you’re sitting at, ignoring every other Linux machine on your LAN
• SSD as scratch space: build/, obj-*/, tmp/, all writing temp files you’ll delete in ten seconds anyway, with the kernel journaling each write

Each tool below kills one of those. Stack them and the compounded win is not 5× or 10×, on a from-scratch rebuild it can hit 20×. On an incremental rebuild after a tiny patch, with ccache warm, you can be looking at a 100× speedup over a cold first build. The Debian project literally documents a 30–70% wall-clock reduction from eatmydata alone on chroot-heavy workflows. We’ll get there.

eatmydata: the world’s most aggressively named tool

The name is a warning and a promise. eatmydata is a small LD_PRELOAD shim that intercepts fsync(2), fdatasync(2), sync(2), msync(2), and the O_SYNC / O_DSYNC open flags, and turns every single one of them into a no-op. That’s it. That’s the tool.

Why does that help so much? Because dpkg is paranoid for very good reasons. When it installs a package on your laptop, it fsyncs every single extracted file before it considers the install complete. If your battery dies mid-install, you want your system to come back up. That’s the right default for production.

It is, however, the absurd default for a build chroot that lives for ninety seconds, gets discarded, and writes nothing you care about. You don’t need crash-safe writes for a tarball you’re going to rm -rf before lunch.

How to use it

apt install eatmydata
eatmydata apt install build-essential ...
eatmydata dpkg -i some.deb
eatmydata make install      # works for anything that calls fsync()

Anything that calls fsync downstream of the wrapper gets the no-op treatment. Wrap your whole build invocation, your apt, your make install, your CI script, wherever the fsyncs are coming from. On a fresh chroot or a from-zero CI environment, the dep-install phase alone often shaves 30 to 70 percent off wall-clock time before gcc has even started.

What it costs

Nothing, as long as you only use it where data loss is fine. Throwaway chroots, CI runs, test databases, scratch builds, local development trees: perfect. Anywhere you’d cry if a power failure corrupted the result: don’t. The name is the manual.

mold: the linker that finally cares about you

For decades, linking was the unspoken final boss of every C and C++ project. You’d compile in parallel across all your cores in twenty seconds, then sit watching one CPU at 100% for forty seconds while ld stitched the object files together. Single-threaded. Memory-hungry. Embarrassing.

gold (Google’s improved linker) helped a bit. lld (LLVM’s) helped more. Then Rui Ueyama, who also wrote lld, looked at the problem fresh and decided to write a linker that was multi-threaded and cache-friendly from the start. The result is mold, and on a typical link step it’s somewhere between 2× and 20× faster than ld.bfd. NGINX with twenty static modules links in about three seconds with mold versus thirty with ld. That’s not a typo.

How to use it

apt install mold

# One-off, for a single build of anything:
mold -run make
mold -run cmake --build .
mold -run ./configure && mold -run make -j$(nproc)

# Per-project, via the standard linker-selection flag:
export LDFLAGS="-fuse-ld=mold"

# System-wide, via update-alternatives (Debian trixie+, Ubuntu 24.04+):
update-alternatives --install /usr/bin/ld ld /usr/bin/mold 100

The mold -run form is the safest, because it intercepts exec*() calls and rewrites /usr/bin/ld to mold just for that command tree. No system-wide change, no surprises in unrelated builds.

What it costs

Almost nothing, in 2026. Three or four years ago mold had rough edges with weird linker scripts (kernel modules, embedded firmware, custom .lds files). Today, on userspace Debian/Ubuntu packages, it’s a drop-in. The one thing to watch: a small handful of packages parse the output of ld --version and choke if they don’t see “GNU ld”, usually configurable, occasionally not. For ninety-nine percent of packages, you’ll never notice.

ccache: don’t compile what you compiled yesterday

The premise of ccache is so obvious that the only mystery is why it isn’t on by default everywhere. It hashes your preprocessor output (or, in direct mode, the source file plus headers plus compiler flags). If it’s seen that exact hash before, it hands you back the cached .o file instead of running gcc. If it hasn’t, it runs the compiler and stores the result.

On a from-scratch build, ccache costs you a few percent (the hashing overhead). On the second build, even after a git pull that touches three files, you’ll see hit rates of 90 to 99 percent and a build that finishes in the time it takes to ld. On our build host, ccache turns a fourteen-minute NGINX rebuild into a ninety-second one. The other minutes are linking, packaging, and signing.

How to use it

apt install ccache

# Make gcc/g++ go through ccache:
export PATH="/usr/lib/ccache:$PATH"

# Or wire it in explicitly via your build's CC/CXX:
export CC="ccache gcc"
export CXX="ccache g++"

# Give it more space — default is 5GB, bump to 40 if you build a lot:
ccache --max-size=40G

# Check hit rate after a few builds:
ccache --show-stats

If your build runs inside a container, a chroot, or any ephemeral environment, mount the ccache directory in from the host so the cache survives across runs. In Docker that’s a -v ~/.ccache:/root/.ccache. In a chroot, a bind mount. In CI, a cache step that restores ~/.ccache between jobs. The pattern is the same everywhere: the wrapper goes inside, the cache directory lives outside.

What it costs

Disk space and one trap. The trap: ccache hashes the compiler binary path and a few sentinel flags. If you build the same source with two slightly different toolchains (say, gcc 14 on Debian trixie and gcc 13 on bookworm) you’ll get cache misses on every file. That’s the right behaviour. But if you accidentally include something volatile in the hash, like an absolute build path or __DATE__, your hit rate will tank. Set CCACHE_BASEDIR to normalize paths, and enable hash_dir=false if you’re sure builds are path-independent.

distcc: turn the office into one big CPU

You have one workstation, one home server, an old laptop in the closet, and a Raspberry Pi running Pi-hole. Combined that’s maybe sixteen cores. distcc says: stop wasting them. Run a tiny daemon on the other machines, point your build at them, and your compile jobs farm out across the LAN.

The trick is that gcc compiles each .c file into a .o file in isolation, no IPC, no shared state. That’s embarrassingly parallel, which is exactly the workload distcc exists to exploit. It runs the preprocessor locally (which needs your headers), ships the preprocessed source to a remote distccd, runs gcc there, ships the .o back.

How to use it

# On every helper machine:
apt install distcc
# Edit /etc/default/distcc — set ALLOWEDNETS=192.168.0.0/16 (or whatever)
systemctl enable --now distcc

# On the build host:
apt install distcc
export DISTCC_HOSTS="localhost/8 helper1.lan/8 helper2.lan/4"
export CC="distcc gcc"
export CXX="distcc g++"

make -j20   # parallelism = sum of all the /N slots above

Combine distcc with ccache by setting CCACHE_PREFIX=distcc, ccache handles the cache, distcc handles the actual compilation on misses. This is the classic stack and it works beautifully.

What it costs

Setup time and trust. Every helper must run the exact same gcc version, the same glibc target, and ideally the same Debian release, or you’ll get binaries that link locally but crash on the build host. Use distcc-pump mode if you want to skip the local preprocessing step (faster, but requires identical header trees). And never expose distccd to the open internet: it’s a remote code execution waiting to happen. ALLOWEDNETS exists for a reason; respect it.

tmpfs: put the whole build in RAM

Modern SSDs are fast. RAM is fifty times faster. A build that thrashes through ten thousand small files in a build/ directory will, no matter how nice your NVMe is, spend most of its time bouncing through the kernel’s page cache, journaling, and waiting on serialised syscalls. Move that directory into tmpfs and the kernel never even touches the disk.

This is the single highest-impact change for incremental rebuilds on a fast desktop. It also has the politest failure mode of every tool in this post: if you run out of RAM, the build fails loudly and obviously instead of producing a corrupted package. (You can also enable swap, but if you do that you’ve just moved the build back to disk, slower than where it started. Don’t.)

How to use it

# Permanent tmpfs scratch:
mkdir /build
echo "tmpfs /build tmpfs size=16G,mode=1777 0 0" >> /etc/fstab
mount /build

# Then point your build at it — examples:
make -C /build -f /path/to/project/Makefile
cmake -B /build/proj -S ~/project && cmake --build /build/proj
git clone ~/project /build/work && cd /build/work && ./configure && make

On a 32 GB workstation, a 16 GB tmpfs is comfortable for any single project build short of LibreOffice, Chromium, or the Linux kernel. For those, fall back to a fast SSD and pair it with eatmydata, you’ll get most of the win without the OOM risk.

What it costs

RAM, and a small amount of caution. tmpfs doesn’t survive reboot, which is exactly what you want for scratch space and exactly what you don’t want for the finished .deb. Make sure your post-build hooks copy the artefacts to durable storage. And don’t point your CCACHE_DIR at tmpfs, that defeats the entire point of a cache.

Putting it all together

Here’s the whole stack as a single shell snippet you can paste in front of any build, make, cmake, autotools, ninja, kbuild, the lot. Each line is independent; comment one out to measure its contribution.

# 1. tmpfs scratch (one-time, in /etc/fstab):
#    tmpfs /build tmpfs size=16G,mode=1777 0 0
cd /build && git clone --depth=1 https://example.org/project src
cd src

# 2. ccache wrappers ahead of real gcc/g++
export PATH="/usr/lib/ccache:$PATH"
export CCACHE_DIR=/build/.ccache
export CCACHE_MAXSIZE=40G

# 3. distcc — farm compiles across the LAN
export CCACHE_PREFIX=distcc
export DISTCC_HOSTS="localhost/8 build2.lan/8 build3.lan/4"

# 4. mold — modern parallel linker
export LDFLAGS="-fuse-ld=mold ${LDFLAGS:-}"

# 5. eatmydata — kill fsync on the install step
./configure --prefix=/build/install
eatmydata make -j$(distcc -j) install

The order in that snippet is also the order to enable them in if you’re starting from scratch. Each one is independently measurable. Time the build after each export and you’ll see exactly where your wall-clock minutes are coming from.

If you do build Debian packages, the same five exports drop into ~/.pbuilderrc, ~/.sbuildrc, a Dockerfile ENV block, or a GitHub Actions env: map with zero changes, the tools don’t care what’s calling them.

Things to watch out for

Three traps catch everyone at least once.

Trap one: eatmydata inside a chroot that escapes to the host. The LD_PRELOAD is process-local, but if a build script does something weird like nsenter into a parent namespace and writes a file there, that write is unprotected by your “I don’t care about fsync” promise. In ninety-nine percent of pbuilder workflows you’re fine. Watch out in custom CI.

Trap two: ccache caching the wrong thing. If your build embeds __DATE__ or __TIME__ in compiled output, every cache hit produces a binary with the wrong embedded timestamp. The Debian project (rightly) considers this a bug, reproducible builds depend on stripping that, but if you maintain an old codebase, audit for these macros first or you’ll ship stale-looking timestamps. Set SOURCE_DATE_EPOCH and call it done.

Trap three: mold plus weird link scripts. Kernel modules, EFI binaries, certain GNU-isms in linker scripts, these are the small remaining edge cases where mold still trips. If your build mysteriously fails at the link step with cryptic relocation errors, unset DEB_LDFLAGS_MAINT_APPEND and try again with the system ld. If that fixes it, file a bug with upstream mold; they’re responsive.

What about Bazel, Nix, sccache, and the rest?

Fair question. sccache is Mozilla’s ccache rewrite in Rust, with optional S3 / Redis backends for sharing the cache across a CI fleet. If you’re running cloud CI it’s worth a look; on a single build host, ccache wins on simplicity. Bazel and Nix achieve similar incremental wins through content-addressed builds, but they require restructuring how you build, which is a much bigger ask than “stick a wrapper in front of gcc.”

The five tools in this post share one virtue: they’re transparent. You don’t change a single line of upstream source. You don’t migrate your CI. You don’t learn a new build system. You install a deb, export a couple of variables, and watch your builds get faster. That’s why they’ve outlived every “next-gen build system” of the past fifteen years and will probably outlive the next ten.

Measuring the win

Don’t take anyone’s benchmarks at face value, including these. Time your own builds before and after, three runs each, throw out the slowest. Use /usr/bin/time -v, not the shell builtin, you want the resident-set-size numbers too so you know you haven’t blown your RAM budget.

/usr/bin/time -v make clean && /usr/bin/time -v make -j$(nproc) 2>&1 | tee before.log
# enable one tool (export PATH=/usr/lib/ccache:$PATH, etc.)
/usr/bin/time -v make clean && /usr/bin/time -v make -j$(nproc) 2>&1 | tee after.log
diff <(grep -E 'wall|user|sys|Max' before.log) \
     <(grep -E 'wall|user|sys|Max' after.log)

The numbers should be unambiguous. If they’re not, you’ve misconfigured something, usually PATH ordering on ccache or a typo in DISTCC_HOSTS. The signal is loud when these tools work; it’s effectively zero when they don’t.

FAQ

Related reading

• How to Install ModSecurity and OWASP CRS on NGINX: once your NGINX builds are fast, here’s what to actually build into it
• What Is Zstd? NGINX, Angie, History and Browser Support: the compression format that the same techniques here let us ship as a dynamic module
• Docker Hardening for Self-Hosters: once builds are fast you’ll start running more of them; here’s how to box them in
• The deb.myguard.nl APT repository: every package on this site is built with the stack in this post

Five tools. Five exports. About an hour to wire it all up. The next time you push a one-line patch and the rebuild finishes before your hand leaves the keyboard, remember: it isn’t magic. It’s just that the defaults were terrible, and someone finally fixed them.

We just fixed that. The repository at deb.myguard.nl/apt now publishes itself in clean, separate trees: one per distribution, and one per package. Same signing key, same packages, same versions, just sorted. This is the story of why a package repository is shaped the way it is, what was wrong with the old shape, and how to use the new one. I’m going to explain it like you’re sixteen and have never set up an APT repo, because honestly most people who run them never had it explained either.

Let’s start with the thing nobody tells you.

What an APT repository actually is (and where the deb.myguard.nl APT repository layout fits)

Here’s the big secret about APT repositories: they’re just a web server with files on it. That’s it. There’s no database, no API, no clever server-side magic. When you run apt update, your computer downloads a couple of plain text files over HTTP, reads them, and goes “ah, okay, here’s what’s available.” When you run apt install nginx, it downloads a .deb file, which is itself just a fancy .tar archive, and unpacks it.

If you can serve a folder of files over HTTP, you can run an APT repository. People act like it’s wizardry. It’s a glorified python3 -m http.server with some rules about folder names.

Those rules matter, though, so let’s look at them. A repository has two important parts:

• The pool/: this is where the actual .deb files live. The packages themselves. The cargo.
• The dists/: this is the index. It’s a set of text files that say “for Debian bookworm, here are the packages we have, here are their versions, here are their SHA256 hashes, and here’s a cryptographic signature proving I really wrote this list.”

When your machine runs apt update, it’s downloading the dists/ index. It never downloads the whole pool/, that would be insane, it’s gigabytes. It downloads the catalogue, decides what it needs, and then fetches only those specific .deb files from the pool/. Think of dists/ as the restaurant menu and pool/ as the kitchen. You read the menu; you don’t walk into the kitchen and eat everything.

The line you put in /etc/apt/sources.list.d/ is just an address telling your machine where the menu is:

deb [signed-by=/etc/apt/keyrings/deb.myguard.nl.gpg] https://deb.myguard.nl/apt/dists/bookworm bookworm main

That reads as: “Go to this URL, look in the dists/bookworm menu, the suite is called bookworm, and I want the main component.” Hold that thought. The shape of that URL is the entire point of this article.

The old layout, and why it was a teenager’s bedroom floor

Back in 2022 we moved from a tool called reprepro to aptly for managing the repo. (Different tools, same job: take a pile of .deb files, generate the signed index, publish it.) And the way it got set up, every Debian and Ubuntu release published straight into the web root. All of them. Into the same physical directory.

So on disk it looked like this, one dists/ with every release crammed in side by side, and crucially, one shared pool/ holding the .deb files for everything:

/                       ← the web root, served at deb.myguard.nl
├─ dists/
│   ├─ bookworm/      ← Debian 12 index
│   ├─ trixie/        ← Debian 13 index
│   ├─ jammy/         ← Ubuntu 22.04 index
│   ├─ noble/         ← Ubuntu 24.04 index
│   └─ ...
└─ pool/
    └─ main/          ← EVERY .deb for EVERY release, all together

It worked fine. APT is perfectly happy with this. But it had two real problems, and they got worse as we added more packages.

Problem one: you got the whole buffet whether you wanted it or not. Say you run a mail server and you just want our Postfix and Dovecot and rspamd. You add the repo, and now apt update pulls down an index that also lists nginx, Angie, MariaDB, a hundred and eight nginx modules, OpenSSL builds, and a pile of shared libraries. Your apt-cache search results get polluted with stuff you’ll never touch. Your apt pinning has to be more careful. It’s noise. A 2 a.m. “why is libnginx-mod-http-vod showing up on my mailserver” kind of noise.

Problem two, and this one actually scared me once, the shared pool/ is a loaded footgun. When everything publishes to the same directory with the same prefix, the publishing tool treats them as one big shared object store. Drop or rebuild one release’s publication, and the tool happily wipes the shared dists/ and pool/ out from under every other release at the same time. I learned this the way everyone learns these things: by doing it once, watching twelve thousand .deb files vanish from the published tree, and feeling my soul briefly leave my body. (They were recoverable from the database. My blood pressure was not.)

So: one messy room, where touching one thing could knock over everything else, and where every guest had to look at all your junk. Time to get some shelves.

The new deb.myguard.nl APT repository layout: shelves, not a pile

The fix is conceptually simple and it’s the same fix your mum suggested for your bedroom: put things in separate, labelled containers. Everything still lives under /apt/, but now it’s sorted two ways at once.

First, the full per-distribution trees. Each release gets its own isolated folder with its own dists/ and its own pool/. Nothing shared. Nothing that can knock over a neighbour:

/apt/dists/
├─ jammy/        ← Ubuntu 22.04 — its own dists/ + pool/
├─ noble/        ← Ubuntu 24.04
├─ bullseye/     ← Debian 11
├─ bookworm/     ← Debian 12
├─ trixie/       ← Debian 13
└─ resolute/     ← Ubuntu 26.04 LTS

This is the one most people want. It’s everything we build for your release, in one source line, completely separated from every other release. The URL is /apt/dists/<codename>, so for Debian 12 it’s https://deb.myguard.nl/apt/dists/bookworm.

Second, and this is the genuinely nice new bit, the per-package trees. Each package gets its own tree, sliced again by release:

/apt/
├─ nginx/
│   ├─ bookworm/    ← just nginx + its deps, for Debian 12
│   ├─ trixie/
│   └─ ...
├─ angie/
├─ postfix/
├─ dovecot/
├─ rspamd/
├─ mariadb/
└─ openssh/

So if you want only our nginx and nothing else cluttering your apt index, you point at /apt/nginx/<codename> and that tree contains nginx, its modules, and the handful of libraries it actually depends on. Nothing else. A mail admin points at /apt/postfix/bookworm and /apt/dovecot/bookworm and never sees a single nginx module.

The old shared layout is still live at the site root, by the way. We didn’t rip it out. It’s marked “being retired” but it keeps working so nobody’s automation breaks the day they read this. You’ve got time to move over. We’re not monsters.

How aptly pulls this off without copying everything ten times

Here’s a question that should bug you: if there’s a full bookworm tree and a separate nginx/bookworm tree, are we storing the nginx .deb twice? Disk is cheap but it’s not free, and copying the same 200 MB of nginx modules into six package trees across six releases adds up fast.

The answer is no, and the trick is hardlinks. When aptly publishes a tree, it doesn’t copy the .deb file into the pool/, it creates a hardlink. A hardlink is a second name for the exact same bytes on disk. Same inode, two directory entries. The file appears in both /apt/dists/bookworm/pool/ and /apt/nginx/bookworm/pool/, costs the disk space of one copy, and if you edit one you edit both (you won’t, published .deb files are immutable). It’s the filesystem equivalent of one band member being in two bands. Same person, two posters.

The per-package trees are built with a technique aptly calls a snapshot pull. We take a snapshot of the whole release, then pull out just one source package and the things it actually depends on. The pull follows hard Depends, not the soft Recommends and Suggests, which is a detail that matters more than you’d think. The first time we built these, we left dependency-following turned all the way up, and Postfix’s “Suggests: a mail reader” dragged the entire Dovecot package set into the Postfix tree. Postfix politely suggesting you might also enjoy a different mail server is true, philosophically, and completely useless in a per-package repo. So: hard dependencies only. Each tree contains the package, its real libraries, and nothing it merely thinks you’d like.

One more detail, because someone always asks: not every package exists for every release. MariaDB only builds for trixie and resolute, because those are the only base systems shipping the MariaDB 11.x build dependencies we need. OpenSSH is wired up but not always populated. The build script just skips a release cleanly when a package isn’t there, instead of publishing an empty broken tree. No 404 surprises.

The signing key: why your computer trusts us at all

Quick detour into the most important file you’ll never look at. Remember how the dists/ index includes “a cryptographic signature proving I really wrote this list”? That signature is made with a GPG key, and your machine needs our public half of that key to check it. No key, no trust, and modern APT will flat-out refuse to install anything.

This is the bit that stops a random person on your coffee-shop WiFi from intercepting your apt update and feeding you a backdoored nginx. Even over plain HTTP, APT verifies every index and every package against the signature. The transport can be untrusted; the math can’t be faked. (This is also why our backup mirror on port 8888 can serve plain HTTP without it being a security problem, the signature check doesn’t care how the bytes arrived.)

Our key lives at one obvious address: https://deb.myguard.nl/deb.myguard.nl.gpg. It’s an RSA 4096-bit key, born 2020-12-27, valid through May 2028. We serve it already in the binary format APT wants, so you don’t even need to run gpg --dearmor on it, just save it into the keyrings folder:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.myguard.nl/deb.myguard.nl.gpg \
  | sudo tee /etc/apt/keyrings/deb.myguard.nl.gpg >/dev/null

Notice we put it in /etc/apt/keyrings/ and reference it with signed-by= in the source line, rather than dumping it in the old /etc/apt/trusted.gpg.d/ where it would be trusted for every repo on your system. Scoping the key to one repo is the modern, correct way to do this. It means our key can only ever vouch for our packages. If you’re the paranoid type, and around here that’s a compliment, verify the fingerprint after you save it:

gpg --no-default-keyring --keyring /etc/apt/keyrings/deb.myguard.nl.gpg --fingerprint

It must read D18B 8E5A DF7D 55CE 2A00 D581 67F9 C3D8 456D 7F62, character for character. If it doesn’t, stop, and don’t run apt update, something fetched you the wrong key.

Actually using it: three ways, pick your fighter

Right, theory’s over. Here’s how you actually add the thing. All three methods use the same key from the step above and end up cryptographically identical, they differ only in how much of the repo you pull into your apt index.

Option 1: the full release tree (recommended)

You want everything we build for your release. This is the default and what most people should use.

apt-get update
apt-get -y install lsb-release ca-certificates curl

CODENAME=$(lsb_release -cs)
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/deb.myguard.nl.gpg] https://deb.myguard.nl/apt/dists/$CODENAME $CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/deb.myguard.nl.list

sudo apt-get update
sudo apt-get install nginx     # or: angie, postfix, rspamd, ...

The $(lsb_release -cs) bit just prints your release codename (bookworm, noble, whatever) so the same commands work everywhere. No editing required.

Option 2: one package only

You want our nginx and literally nothing else in your apt index. Point at the package’s own tree:

CODENAME=$(lsb_release -cs)
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/deb.myguard.nl.gpg] https://deb.myguard.nl/apt/nginx/$CODENAME $CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/deb.myguard.nl-nginx.list

sudo apt-get update
sudo apt-get install nginx

Swap nginx for angie, postfix, dovecot, rspamd, mariadb or openssh. You can stack several, give each its own file in sources.list.d/ (like deb.myguard.nl-postfix.list) so they’re easy to manage and remove later. Want to see every tree that exists right now? Just open deb.myguard.nl/apt in a browser and click around. It’s a plain directory listing. The whole menu, visible.

Option 3: the lazy way (the bootstrap package)

If you trust us and just want it working now, we ship a tiny .deb that does the key install, the source line, and the apt pinning for you:

apt-get update
apt-get -y install lsb-release ca-certificates curl

curl -fsSLO https://deb.myguard.nl/myguard.deb
sudo dpkg -i myguard.deb
sudo apt-get update

Its install script detects your codename, writes the signed-by source pointing at the new /apt/dists/<codename> tree, drops in the signing key, and sets pinning so our builds win version ties. It’s a normal .deb, if you want to audit it, dpkg-deb -R myguard.deb out/ and read the postinst yourself. We’d respect you more for it.

A word on pinning (the thing that decides who wins)

Here’s a subtlety that trips people up. Say Debian ships nginx 1.22 and we ship a hardened nginx 1.31. You’ve added our repo. Which one does apt install nginx give you? By default APT picks the highest version number, but version comparison across repos gets weird fast, and you don’t want to leave it to chance.

That’s what pinning is for. A pin file in /etc/apt/preferences.d/ says “packages from this origin get priority.” The bootstrap package sets this up automatically, pinning on the repository’s Origin field, which, across all our trees, is deb.myguard.nl. (Getting that Origin consistent across the new per-distro trees was its own small adventure; when you split a repo into pieces, every piece has to remember its own name, and the first build forgot. Fixed now.) If you set the repo up by hand and want our builds to take priority everywhere, the how-to page has the exact pin snippet.

If you only want, say, our nginx but Debian’s everything-else, you can pin more narrowly, or just use the per-package tree from Option 2, which sidesteps the whole question by only offering one package in the first place. Sometimes the cleanest pin is not needing one.

Why this matters beyond tidiness

It would be easy to file this under “cosmetic spring cleaning,” but there’s real engineering payoff.

Smaller, faster apt update. A per-package tree’s index lists a handful of packages, not twelve thousand. If you’re provisioning a fleet of mail servers and they each only need the Postfix tree, every apt update across that fleet parses a tiny index instead of the whole catalogue. Multiply by a few hundred machines and a few times a day and it stops being theoretical.

Blast radius. Separate trees with separate pools mean a publishing mistake on one can’t nuke the others. The footgun from the old layout is structurally gone, not “we’ll be careful,” but “the tool physically can’t reach the neighbour’s files.” That’s the difference between a safety habit and a safety property, and the second one is the only kind you can trust at 2 a.m.

Clarity. You can browse to deb.myguard.nl/apt and see the shape of what we publish. Which packages, which releases, what’s in each. A repo you can read with your eyes is a repo you can reason about. No guessing, no spelunking through one enormous flat Packages file.

If you want the practical, no-theory version of all this, just the commands to copy, the how-to-use page is the cheat sheet. And if you came here because you’re setting up a hardened stack from scratch, the nginx modules we ship and the ModSecurity + OWASP CRS guide are the obvious next stops. Mail people: the rspamd explainer pairs nicely with the Postfix and Dovecot trees.

A package repository is just a folder of files on a web server. But the shape of that folder is a promise about how much junk you have to accept to get the one thing you wanted. We just made that promise a lot smaller.

Frequently asked questions

Related reading

• How to Add the myguard APT Repository (Debian & Ubuntu): the copy-paste cheat sheet for everything above.
• NGINX Modules, optimized & extended: the full list of what’s in the nginx tree.
• How to Install ModSecurity and OWASP CRS on NGINX: turn your new nginx into a web application firewall.
• Rspamd Explained: the brains behind the Postfix and Dovecot trees.

The problem is that “small on purpose” has aged into “small in a way that hurts.” Want async/await with a real microtask queue? Want BigInt for a counter that exceeds 2⁵³? Want to import() a helper module only when a specific path is hit? Want a regex with a lookbehind because you’re parsing a header field? On stock njs the answer is some variant of “no”, “almost”, or “yes but rewrite it like it’s 2013”. So we did the obvious thing: we rebuilt njs against QuickJS-NG, the maintained fork of Fabrice Bellard’s QuickJS engine, and now you get a proper ES2023 runtime in every js_set, js_content, js_body_filter and js_periodic on the box. This is the long version of why that matters, what it changes, and how to use it.

What njs actually is, for the people who skipped the docs

njs (short for “NGINX JavaScript”, and yes it should have been “ngs”) is a dynamic module for NGINX. You load it, you point it at a .js file, and from that moment on every request can pass through JavaScript on its way to and from the upstream. Two flavours: ngx_http_js_module for the HTTP layer, where most people use it, and ngx_stream_js_module for the L4 stream layer, where you can rewrite SNI, inspect PROXY protocol, do dynamic upstream selection, that kind of thing. Same engine, same scripts, different request lifecycle hooks.

What does “passing through JavaScript” mean in concrete terms? You wire it up with one of half a dozen directives:

• js_set $variable function: variable is set by running function(r) at the moment NGINX needs the value. Great for computed headers, signed URLs, request signatures, anything you’d otherwise reach for Lua for.
• js_content function: the whole response body is produced by JavaScript. Replaces the upstream entirely.
• js_body_filter function: runs as a streaming filter, sees the response in chunks, can transform on the fly without buffering the full document.
• js_header_filter function: same idea but for response headers.
• js_periodic function interval=N: run a function every N seconds, outside the request path. Great for refreshing caches, polling a control plane, sending stats to a downstream collector.
• js_import name from path: the module-loading directive. Everything above refers to functions exported from these imports.

If you’ve ever written OpenResty Lua, the mental model is the same: pluggable code at well-defined phases of the request, with a request object (r in njs, ngx in Lua) that gives you access to headers, args, body, variables, and subrequest helpers. njs is younger, smaller, and ships in the official NGINX repo. That’s its pitch. Its other pitch, until now, was a sharply restricted language.

The “njs doesn’t have that” wall, in detail

The stock njs interpreter is, per its own compatibility page, an ES5.1 strict-mode subset plus a hand-picked grab bag of ES6+ features. The picks are reasonable on paper, let, const, arrow functions, template literals, basic Promises, the spread operator, but the omissions are where you lose your afternoon.

Concrete things people walk into and bounce off:

• Promises that interleave with the I/O loop. Stock njs has a Promise constructor and you can chain .then(), but the microtask semantics are bolted on rather than woven in. Real async/await with the natural “await my subrequest, then await this other subrequest, then return the combined header” pattern? Either contorted or unreliable depending on njs version.
• BigInt. Not there. Counters above 2⁵³, certificate serials, monotonic timestamps in nanoseconds: you reach for it the second you need it, and it’s just gone.
• Proxy and Reflect. Useful for the kind of meta-programming where you’d wrap a config object so unknown keys throw with a helpful error. Not there.
• Dynamic import(). Stock njs has js_import at the config level, so you can preload modules at startup, but you can’t conditionally load a helper from inside a request handler when a specific route fires. That’s a real limitation when half your scripts are dead code for the other 90% of routes.
• Modern regex. No lookbehind (?<=...), named capture groups are spotty, Unicode property escapes \p{L} aren’t there. Try parsing a Forwarded: header with the elegant lookbehind regex from MDN and watch your config refuse to load.
• Intl. No locale-aware toLocaleDateString, no NumberFormat. Want a localised cache key based on Accept-Language? You’re writing a switch.
• ES modules with full semantics. Stock njs supports modules but the boundaries are blurry: top-level await doesn’t work, dynamic exports are limited, and you can’t really mix module styles cleanly.

None of this is njs being lazy. The original goal was a fast, tiny, embeddable engine for high-RPS web servers, and the team made deliberate cuts to keep the per-request cost low. The engineering trade is real. But for anyone copying patterns from Node, modern blog posts, or, let’s be honest, a chatbot’s autocomplete, the surface mismatch is constant friction.

Enter QuickJS-NG: ES2023, in a binary smaller than your average cat picture

QuickJS started as a side project from Fabrice Bellard, the same Fabrice Bellard who wrote FFmpeg, QEMU, the world’s smallest x86 emulator, and an arbitrary-precision arithmetic library because Tuesday. QuickJS shipped in 2019 as a tiny, complete, embeddable JS engine: under a megabyte stripped, passing nearly all of test262 (the official ECMAScript conformance test suite), no JIT, no GC tuning headaches, just a bytecode interpreter with inline caches and a reference-counted heap.

Bellard’s original repo went quiet after a year. The community forked it into QuickJS-NG, “next generation”, and that fork is what’s actually maintained now: regular releases, ES2023 feature work, security fixes, and a steady drip of performance improvements. As of 2026, QuickJS-NG passes the overwhelming majority of test262, including the corners njs doesn’t even try to reach. It’s the engine of choice when you want real JavaScript without dragging Chromium into the build.

The relevant features it gives you, off the shelf:

• Proper Promise with woven microtask scheduling, real async/await, Promise.allSettled, Promise.any.
• BigInt with the full operator set and literal syntax (123n).
• Symbol, WeakRef, FinalizationRegistry.
• Proxy and Reflect.
• Full ES modules including dynamic import(), top-level await in modules, re-exports.
• Generators and async generators.
• Modern regex: lookbehind, named groups, Unicode property escapes, the d flag for indices.
• Tagged templates, optional chaining (?.), nullish coalescing (??), logical assignment (??=, &&=, ||=).
• Intl for locale-aware formatting (when built with ICU; we ship it).
• Array.prototype.at, findLast, group, the whole class-fields-and-private-methods family.

That’s the language. The question is how to plug it into njs so the rest of your NGINX config doesn’t care which engine is underneath.

How our build glues the two together

njs itself has a documented hook for “use an external QuickJS as the engine instead of the bundled one.” Its nginx/config probe runs pkg-config quickjs-ng at configure time, and if it finds a quickjs-ng.pc file with sane --cflags and --libs, the dynamic njs module is compiled against that QuickJS instead. If the probe fails, njs silently falls back to its own embedded interpreter, exactly the failure mode we don’t want, because the only thing worse than a missing feature is a runtime that quietly downgrades.

So our deb/nginx/debian/rules does three things, in order, every build:

1. Vendors QuickJS-NG as a git submodule under modules/nginx/quickjs-ng/, so the source is pinned and reproducible.
2. The build_quickjs_ng make target runs cmake, builds and installs QuickJS-NG into a per-build staging prefix (debian/.quickjs-ng/), and writes a hand-crafted quickjs-ng.pc pointing at that prefix.
3. The staging prefix’s lib/pkgconfig is prepended to PKG_CONFIG_PATH before NGINX’s ./configure runs. njs’s probe sees it, compiles against it, links against it. Done.

One critical detail: the make target is fatal on any failure. If cmake isn’t in the pbuilder chroot, if the submodule didn’t unpack, if the .pc file fails to write, the build aborts loud and red. We deliberately do not let it silently fall back to the bundled interpreter. The whole point of shipping libnginx-mod-http-njs on this repo is that it’s the QuickJS-NG flavour. If it’s not, you’ve been mis-sold a package.

The same vendoring lives in deb/angie-nextgen/, Angie is our other nginx flavour and ships the same module with the same backend. One source of truth, two consumers.

The language-completeness delta, with copy-pasteable examples

Let’s walk through the things that go from “awkward or impossible” on stock njs to “boring and obvious” on the QuickJS-NG build. Every snippet below is real njs you can drop into a js_import‘d module.

Real async/await with subrequests

async function combinedAuth(r) {
    const [user, perms] = await Promise.all([
        r.subrequest('/auth/whoami',  { method: 'GET' }),
        r.subrequest('/auth/perms',   { method: 'GET' }),
    ]);
    if (user.status !== 200 || perms.status !== 200) {
        r.return(401);
        return;
    }
    const u = JSON.parse(user.responseText);
    const p = JSON.parse(perms.responseText);
    r.headersOut['X-User']  = u.name;
    r.headersOut['X-Perms'] = p.scopes.join(',');
    r.return(204);
}
export default { combinedAuth };

On stock njs this exists in some form, but Promise.all with two subrequests has historically misordered microtasks in ways that hit you only under load. On the QuickJS-NG build it behaves like Node: the two subrequests start, the await yields, both complete, the rest of the function runs. Boringly correct.

BigInt for a real counter

let totalBytes = 0n;
function trackBytes(r) {
    totalBytes += BigInt(r.headersOut['Content-Length'] ?? '0');
    r.variables.total_bytes = totalBytes.toString();
}
export default { trackBytes };

That 0n literal alone wouldn’t parse on stock njs. With QuickJS-NG it’s the natural way to keep a 64-bit running total of bytes served per worker without silent overflow at four petabytes. (Yes, you’ll probably restart the worker before then. That’s not the point.)

Dynamic import() to lazy-load a helper

async function maybeSlowHandler(r) {
    if (r.uri.startsWith('/admin/')) {
        const { expensiveAuth } = await import('./admin-auth.js');
        return expensiveAuth(r);
    }
    r.return(204);
}
export default { maybeSlowHandler };

Stock njs loads everything at config-parse time. With QuickJS-NG dynamic import() works, so admin-only modules are read off disk only when the admin path is hit. For modules that pull in a few hundred kilobytes of token-signing code, that’s a real win.

Modern regex for a header you actually need to parse

// Pull the client IP out of a Forwarded: header per RFC 7239.
const FORWARDED = /(?<=for=)"?(?<ip>\[[\da-fA-F:]+\]|[\d.]+)"?/;
function clientIp(r) {
    const m = (r.headersIn['Forwarded'] || '').match(FORWARDED);
    return m?.groups?.ip ?? r.remoteAddress;
}
export default { clientIp };

Lookbehind, named groups, optional chaining, nullish coalescing, every feature in that one-liner is unavailable or partial on stock njs, and trivial on the QuickJS-NG build.

Intl for a locale-aware cache key

function priceCacheKey(r) {
    const locale = r.headersIn['Accept-Language']?.split(',')[0] || 'en-US';
    const today  = new Intl.DateTimeFormat(locale, { dateStyle: 'short' })
                       .format(new Date());
    return `${locale}|${today}`;
}
export default { priceCacheKey };

Real Intl with the underlying ICU data means the date string actually matches what the user’s browser would display. On stock njs you’d hand-roll a locale switch and feel bad about it.

Proxy for a config object that yells at you

const config = new Proxy({ ttl: 60, region: 'eu-west-1' }, {
    get(t, k) {
        if (!(k in t)) throw new Error(`config key '${String(k)}' not set`);
        return t[k];
    },
});
function withConfig(r) {
    r.headersOut['X-Cache-TTL'] = config.ttl;
    r.return(204);
}
export default { withConfig };

Typos in config keys become loud errors at request time instead of silent undefined values that propagate two functions deep. Stock njs: no Proxy, no luck.

A worked example: JWT validation in 40 lines

The classic njs use case. You sit NGINX in front of an upstream that wants Bearer tokens, you don’t want the upstream to do the verification on every request, and you want NGINX to drop bad tokens at the edge. Stock njs makes you do it, but the code reads like 2014. Here’s what it looks like on the QuickJS-NG build, with real async/await, real Uint8Array crypto, real base64url, optional chaining the whole way down:

import crypto from 'crypto';

const SECRET = process.env.JWT_SECRET ?? 'replace-me-in-prod';

function b64urlDecode(s) {
    s = s.replace(/-/g, '+').replace(/_/g, '/');
    while (s.length % 4) s += '=';
    return Buffer.from(s, 'base64');
}

async function verifyJwt(r) {
    const auth = r.headersIn['Authorization'];
    const tok  = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
    if (!tok) return r.return(401, 'no token\n');

    const [hB64, pB64, sB64] = tok.split('.');
    if (!hB64 || !pB64 || !sB64) return r.return(401, 'malformed\n');

    const head = JSON.parse(b64urlDecode(hB64).toString('utf8'));
    if (head.alg !== 'HS256') return r.return(401, 'bad alg\n');

    const expected = crypto
        .createHmac('sha256', SECRET)
        .update(`${hB64}.${pB64}`)
        .digest('base64')
        .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');

    if (expected !== sB64) return r.return(401, 'bad sig\n');

    const claims = JSON.parse(b64urlDecode(pB64).toString('utf8'));
    if (claims.exp && claims.exp * 1000 < Date.now())
        return r.return(401, 'expired\n');

    r.headersOut['X-JWT-Sub']    = claims.sub  ?? '';
    r.headersOut['X-JWT-Scopes'] = claims.scope ?? '';
    r.return(204);
}
export default { verifyJwt };

Wire it into nginx.conf as:

load_module modules/ngx_http_js_module.so;

http {
    js_import jwt from /etc/nginx/njs/jwt.js;

    server {
        listen 443 ssl;
        location /api/ {
            auth_request /_jwt_verify;
            proxy_pass http://upstream;
        }
        location = /_jwt_verify {
            internal;
            js_content jwt.verifyJwt;
        }
    }
}

That’s a complete, production-shaped JWT gate. Every modern-JS feature in it (optional chaining, nullish coalescing, template literals with backtick interpolation, async, Buffer arithmetic, the crypto module) is the QuickJS-NG side of the fence. None of it requires you to think about which engine is underneath, the script just runs, the way a Node developer would expect.

What it costs you

Nothing’s free. The honest trade-offs:

• Memory. Each QuickJS-NG VM is a bit bigger than a stock njs interpreter. We’re talking single-digit megabytes per worker, not gigabytes. If you’re tuning a 64-worker box to within an inch of its life this matters; if you’re running four workers and 64 GB of RAM, you’ll never notice.
• Build dependency. The package build needs cmake and a C++ compiler in the chroot to compile QuickJS-NG. Our pbuilder configs already include them. If you’re rebuilding from source on a stripped-down environment, that’s one more apt-get.
• Cold start. The QuickJS-NG bytecode compiler is slightly slower than stock njs on first parse. NGINX caches compiled modules per worker, so this only matters at startup or after a reload. For most workloads, invisible.
• Steady-state throughput. Comparable on tiny scripts, often faster on compute-heavy ones thanks to QuickJS-NG’s inline caches. We’ve seen 10–30% gains on token-signing hot paths, partly because the modern syntax lets you write tighter code in the first place.
• Behavioural drift. A script that worked on stock njs by accident: for example by relying on a quirk of how its native Promise queued, might behave differently on the QuickJS-NG build. We’ve not seen this bite anyone in practice, but it’s worth knowing.

Using it on our packages

If you’ve added the myguard apt repo the install is one command:

apt install libnginx-mod-http-njs libnginx-mod-stream-njs

Or, on the Angie flavour:

apt install angie-module-njs

The Debian post-install drops a /etc/nginx/modules-enabled/50-mod-http-njs.conf snippet that loads the module, restart NGINX and the directives are available. Drop your .js files anywhere (we recommend /etc/nginx/njs/), js_import them, and you’re done. There’s nothing njs-specific about which scripts work, if it parses as ES2023 and only uses r. / ngx. APIs, it’ll run.

The module’s section on the synopsis page, directives, syntax, examples, lives at /nginx/modules-synopsis/#njs. The full module list with descriptions is at /nginx-modules/ for NGINX and /angie-modules-optimized-extended/ for Angie. Both pages call out QuickJS-NG explicitly in their bundled-libraries section, so when a future you wonders why your BigInt literal works, the answer is on the same page as the install command.

Frequently asked questions

Related reading

• HTTP/3 and QUIC on NGINX: real-world setup, tuning, and gotchas: the other big NGINX feature we ship enabled by default.
• The zstd NGINX module: what it does and the bugs we fixed: another module on this build that gets a heavier than usual amount of love.
• Hardened OpenSSH 10.3 for Debian and Ubuntu: the same hardening philosophy applied to the SSH side of your stack.
• Self-hosting Aptly behind NGINX: how this repository itself is served, in case you want to build your own.

Pick a function. Open the docs. Drop in a script. The walls aren’t there anymore.

This is a tour of what’s actually new in Postfix 3.11, why post-quantum key exchange in SMTP is not just security theatre, and how the deb.myguard.nl Postfix package and the matching eilandert/postfix container build it. There is config you can paste, history you can blame, and one moderately bad joke about Sendmail. Buckle in.

A very short history of why Postfix exists

Sendmail, written by Eric Allman in 1981, was the canonical Unix MTA for fifteen years. It also had an exploit surface that read like a recipe book: setuid root, monolithic, with a configuration file generated from m4 macros that no human could review by eye. Through the mid-1990s, CERT advisories naming Sendmail averaged one every few months. Wietse Venema, who had a track record of writing security-grade software (the original tcp_wrappers shipped with most Linux distributions), spent his sabbatical at IBM Research building an MTA that started from a different first principle: nothing runs as root that doesn’t have to.

The Postfix architecture is a bunch of little daemons under the master process, each chrooted, each running as the unprivileged postfix user, each talking to its neighbours over a private socket. The SMTP server (smtpd) accepts mail. The cleanup daemon rewrites headers. The queue manager (qmgr) decides what gets delivered next. The SMTP client (smtp) ships mail outbound. If any one of them gets pwned, the blast radius is the privileges that one daemon had, which is almost nothing. Compare that to a monolithic MTA where a parser bug means root.

The trade-off is that Postfix talks to itself a lot. A single inbound message touches at minimum five processes. On modern hardware this is invisible. On a Pentium II in 1999 it was a real concern, and the design choice paid off only because Venema is paranoid about memcpy. Performance matters, but not as much as not getting owned by a malformed SMTP envelope.

What is actually new in Postfix 3.11

Postfix’s release cadence is glacial by modern software standards, and that’s a feature. Wietse ships a new stable train roughly once a year. The 3.10 line landed in February 2025 and introduced TLSRPT (more on that below). 3.11.0 went out on 5 March 2026, with 3.11.1, 3.11.2 and 3.11.3 following over the next two months. The headline items:

• Default smtp_tls_security_level = may. When compatibility_level is 3.11 or higher and Postfix was built with TLS support, outbound mail attempts opportunistic TLS by default. For decades the default was “no TLS unless you set it”, which made sense in 2002 and was embarrassing by 2025. New compatibility level, new default.
• Deletion of smtpd_tls_eecdh_grade and friends. The old “strong/ultra” curve-grade settings were superseded by tls_eecdh_auto_curves in Postfix 3.6 and quietly ignored ever since. 3.11 deletes them outright. If you still have smtpd_tls_eecdh_grade = ultra in main.cf, postconf now warns and tells you to remove it.
• Post-quantum TLS via OpenSSL 3.5. The infrastructure landed in the 3.10 cycle, but 3.11 is the first stable release where it sees actual use. You list hybrid KEM groups in tls_eecdh_auto_curves and the SMTP TLS handshake negotiates X25519MLKEM768 when both ends support it.
• Berkeley DB phase-out. Debian and several other distributions are removing Berkeley DB. Postfix 3.11 ships migration helpers: a stand-alone reindexer service, automatic $default_database_type substitution in alias_maps, and a long NON_BERKELEYDB_README appendix on the migration. The package on deb.myguard.nl defaults to cdb for lookups and lmdb for caches, which dodges the issue entirely.
• SQLite quoting safety. The SQLite map client now logs a warning when a query uses double-quoted string literals instead of single quotes. Double-quoting in SQLite is a footgun that bypasses SQL injection protection; getting a loud warning beats a silent compromise.
• TLSRPT support hardened. The 3.10 line introduced it. 3.11 added routine logging of TLSRPT success and failure events, an option to suppress reports for reused TLS sessions, and a library API version check so a mismatched libtlsrpt won’t silently misbehave.
• Lots of small portability and bugfix work. Three Bugfix entries credit “Claude Opus 4.6” as the finder, which is the first time I’ve seen an LLM credited in upstream Postfix history. The robots are reading proxymap.c. Make of that what you will.

Post-quantum TLS in SMTP: why now?

Here’s the threat model in one sentence. A sufficiently large quantum computer with enough qubits can run Shor’s algorithm against the discrete log problem that ECDHE and RSA-KEX rely on, and recover the symmetric session key from a recorded handshake. That computer does not yet exist. But state-level adversaries are recording encrypted traffic today on the bet that the computer will exist within fifteen years, and at that point everything captured today gets decrypted. The industry calls this “harvest now, decrypt later”, and it’s the reason every cryptography body on Earth started shipping post-quantum algorithms in late 2024.

The standardised winner from NIST is ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism), formerly known as Kyber, formally specified in FIPS 203 in August 2024. ML-KEM-768 (the medium security parameter set) is the version that ended up everywhere, Cloudflare, Google, Apple, OpenSSH 9.9, and OpenSSL 3.5. Crucially, no one runs ML-KEM alone. Lattice cryptography is young, and a bug in the lattice could break ML-KEM the way the lattice CRYSTALS-Dilithium signature scheme had a near-miss last year. So every deployment uses a hybrid: classical X25519 + ML-KEM-768 in parallel, and the session key is derived from both. The handshake breaks only if both schemes do.

In TLS 1.3, the hybrid groups have IANA-registered names. The two that matter for Postfix are X25519MLKEM768 (code point 0x11EC) and SecP256r1MLKEM768 (0x11EB). Both ship in OpenSSL 3.5 (April 2025) and are picked up automatically by Postfix’s TLS layer once you list them in tls_eecdh_auto_curves. The classical curves go after them as a fallback, in case the remote MTA is still running an OpenSSL old enough to lack PQ support.

The Postfix configuration to enable it is two lines:

tls_eecdh_auto_curves = X25519MLKEM768 SecP256r1MLKEM768 X25519 prime256v1 secp384r1
tls_ffdhe_auto_groups = ffdhe3072 ffdhe4096

Test the handshake with a one-liner against your own MTA. -groups X25519MLKEM768 forces the client to offer only that group. If the server picks it, you get Negotiated TLS1.3 group: X25519MLKEM768 in the output. If the server does not support it, the handshake fails outright (which is the point of the test, you want a hard signal, not a silent downgrade):

openssl s_client -connect mail.example.com:25 -starttls smtp \
  -groups X25519MLKEM768 2>&1 | grep Negotiated

One important caveat. SMTP is opportunistic. Two MTAs that don’t share a single PQ group will still negotiate a classical curve and the mail still flows. That’s the right behaviour for an MTA, better to deliver mail on a classical curve than reject it because the recipient hasn’t upgraded yet. The PQ benefit is therefore population-wide and gradual: every server that adds the groups raises the percentage of traffic that’s recorded-but-uncrackable. We’re maybe 4% of inter-MTA traffic right now. By 2028, it’ll probably be most of it.

Anti-spam in Postfix: postscreen, access restrictions, and where rspamd takes over

Postfix has three layers of spam defence that run before the message even hits the queue. Each rejects a different category, and each is cheap because it happens before any disk write.

Postscreen: the bouncer at the front door

postscreen is a separate daemon that listens on port 25 instead of smtpd, and its only job is to decide whether the connecting IP deserves to talk to a real SMTP server at all. It scores the connection against weighted DNSBLs, watches for protocol violations (pre-greet pipelining, bare newlines, malformed commands), and either drops the connection or hands it off to smtpd. The deciding rule is the postscreen_dnsbl_threshold score, anything at or above the threshold gets a 521 disconnect.

The trick is choosing DNSBLs that are alive and not noisy. The mail filter landscape has thinned dramatically since 2020. SORBS shut down in June 2024 when Proofpoint pulled the funding. WPBL went away around 2021. The Lashback UBL is gone. Several SpamRats zones return wildcards now. If your postscreen_dnsbl_sites still lists any of those, you’re paying DNS lookup latency for zero benefit.

A defensible 2026 postscreen list, scoped tight to “really worst offenders only”:

postscreen_dnsbl_threshold = 3
postscreen_dnsbl_sites =
  zen.spamhaus.org*3,
  dnsbl.dronebl.org*2,
  truncate.gbudb.net*2,
  z.mailspike.net=127.0.0.2*100,
  list.dnswl.org=127.0.[0..255].[1]*-4,
  list.dnswl.org=127.0.[0..255].[2]*-6,
  list.dnswl.org=127.0.[0..255].[3]*-9

Spamhaus Zen combines SBL (the manually curated naughty list, which includes the EDROP feed of hijacked netblocks), XBL (botnet C2), and PBL (dynamic IP ranges that should never be sending mail directly). Dronebl is botnet-only. Truncate.gbudb.net is extremely conservative, it lists only IPs with a substantial pattern of repeat abuse. Mailspike’s z. zone gets weight 100 because a single hit is dispositive. And the negative-weight dnswl entries can rescue a borderline-suspect-but-legitimate sender.

If you already run a heavy content filter behind Postfix, and you should, you can drop Spamhaus from the postscreen list entirely. The rspamd RBL module queries Zen at content-scan time anyway. Letting rspamd handle reputation lookups centralises policy and avoids redundant DNS. See the deep dive on rspamd for what it can do that postscreen cannot.

smtpd access restrictions: envelope sanity

Once a connection has cleared postscreen, smtpd‘s access restrictions kick in. These are Postfix’s terminology for what the rest of the world sometimes calls “anti-spoofing” rules. They look at the SMTP envelope, the HELO argument, the MAIL FROM, the RCPT TO, and reject obvious forgeries before the DATA phase. The big ones:

• reject_invalid_helo_hostname and reject_non_fqdn_helo_hostname: drops clients that say HELO foo instead of their actual FQDN. Real MTAs always send a proper FQDN.
• reject_unknown_sender_domain: looks up the sender domain in DNS. If it has no A, MX or AAAA record, the address can’t possibly receive a bounce. Drop the message.
• reject_non_fqdn_sender and reject_non_fqdn_recipient: refuses MAIL FROM:<bob@local> and similar bareword addresses.
• reject_unauth_destination: the rule that makes you not an open relay. If we are not the final destination for the recipient and the sender isn’t in mynetworks or SASL-authenticated, refuse to relay. This single line is the difference between “mail server” and “spammer’s tool”.
• reject_unauth_pipelining: clients that send multiple SMTP commands in one TCP packet before negotiating PIPELINING are almost certainly spam bots trying to dump payload faster than the server can refuse it.
• disable_vrfy_command and strict_rfc821_envelopes: close off the username-enumeration vector and reject envelopes that don’t use angle brackets properly.

Together these eight rules reject something like a fifth of all spam attempts before DATA ever runs, which is the cheapest spam to refuse. None of them involve content inspection. None require DKIM verification. They’re pure envelope sanity, and they’re free.

TLSRPT: SMTP finally gets a delivery receipt for crypto

TLSRPT (TLS Reporting, RFC 8460) is the answer to a question nobody could previously answer: are remote MTAs actually using TLS when they deliver mail to me? For two decades the answer was “look at the Received: headers and hope”. TLSRPT publishes a TXT record at _smtp._tls.example.com with an email or HTTPS endpoint, and remote MTAs send daily JSON reports listing every TLS handshake (and every failed one) for traffic destined to your domain. You get aggregated visibility into who’s downgrading, who’s tripping over expired certs, and who’s still on TLS 1.0.

Postfix 3.10 was the first stable release with TLSRPT support, built against Wietse’s own libtlsrpt. 3.11 added the smtp_tlsrpt_skip_reused_handshakes knob (default yes) so you don’t drown in reports for connection-reused sessions that don’t have new TLS data to report. The library API version is now checked at startup, which catches the case where Postfix was built against one libtlsrpt and is running against a newer incompatible one.

If you’re the recipient publishing the TXT record, the report ingestion problem is yours, not Postfix’s, Postfix is the sending side that generates reports. Tools like parsedmarc handle the aggregation side. Worth it if you operate a domain that actually receives mail at volume; mostly noise if you’re a personal server.

Milters: the surgical content-filter API

Sendmail introduced milters (mail filters) in 2002 as a stable plugin ABI for content scanning. The protocol speaks over a Unix or TCP socket; the MTA streams envelope and headers and body to the milter, and the milter responds with verdicts (accept, reject, quarantine, modify headers, rewrite body). Postfix implemented the same protocol in version 2.3 (2006). The result is that anything that speaks milter, and a lot does, works with both MTAs.

The big four in modern deployments:

• OpenDKIM: signs outbound mail with your DKIM key, verifies inbound DKIM signatures. Postfix asks it for a verdict per message; OpenDKIM hands back a verified-or-not result that ends up in the Authentication-Results: header.
• OpenDMARC: applies the DMARC policy (your domain’s _dmarc TXT record) on inbound mail. Quarantine, reject, or pass depending on what the sender’s DNS says.
• rspamd: connects as a milter on port 11332 and runs the entire content-filter pipeline (Bayesian, neural net, RBL, URIBL, OLEFY, DCC, Razor, Pyzor, neural) before smtpd takes the DATA phase. See the rspamd article for what’s actually inside that pipeline.
• Amavis / ClamAV: virus and macro-payload scanning. Slower than rspamd, but it scans MIME attachments deeply and catches malware that pure-text reputation systems miss.

Postfix lets you chain milters in a comma-separated list, with order-of-execution semantics. Common practice: OpenDKIM and OpenDMARC first (they’re cheap header checks), rspamd second (the heavy lifter), Amavis last (slowest, and you don’t want to scan with ClamAV mail that rspamd already rejected). The configuration on a typical mailscreen:

smtpd_milters     = inet:127.0.0.1:8891, inet:127.0.0.1:8893, inet:rspamd:11332
non_smtpd_milters = $smtpd_milters
milter_default_action = tempfail
milter_protocol = 6

milter_default_action = tempfail is important. If a milter goes down, you want Postfix to issue a 4xx temporary failure so the remote MTA queues and retries, not a 5xx hard bounce. Setting it to accept means broken milters silently let everything through, which is exactly the security regression you’d expect.

How the deb.myguard.nl Postfix package is built

The postfix binary on deb.myguard.nl is built from upstream 3.11.3 source, on Debian trixie and Ubuntu resolute, with a hardened toolchain configuration that’s worth describing because it shows what “secure compilation” actually means in 2026:

DEB_BUILD_MAINT_OPTIONS = hardening=+all optimize=+lto future=+lfs
DEB_CPPFLAGS_MAINT_APPEND = -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3
DEB_CFLAGS_MAINT_APPEND   = -O3 -fno-plt -fstack-clash-protection -fcf-protection=full
DEB_LDFLAGS_MAINT_APPEND  = -Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-O1 -Wl,--as-needed

What that buys you, in plain terms:

• FORTIFY_SOURCE=3: the compiler emits bounds-checking wrappers around memcpy, strcpy, sprintf and friends. Level 3 catches more than level 2 by using whole-program object-size analysis.
• -fstack-clash-protection: prevents stack-overflow attacks that jump past the guard page.
• -fcf-protection=full: Intel CET (Control-flow Enforcement Technology) and AMD SHSTK markers. Hardware-enforced shadow stack, where the CPU itself refuses returns to a hijacked address. Requires Tiger Lake / Zen 3 or newer to actually fire, but the binaries are tagged for it on older CPUs and ignored.
• -z now -z relro -z noexecstack: fully bind all dynamic symbols at load time, mark the GOT read-only after relocation, and forbid stack execution. The trifecta that turns most write-what-where bugs into mere crashes.
• -O3 -fno-plt: aggressive optimization plus no procedure-linkage-table indirection. Skip the PLT and let the linker resolve calls directly through the GOT; smaller dispatch path, marginal perf win.

Beyond compilation, the package ships a hardened default main.cf with the TLS settings from this article already in place (TLSv1.2+ floor, PFS-only cipher list, X25519MLKEM768 hybrid PQ, NO_COMPRESSION / NO_RENEGOTIATION / NO_TICKET, all the smtpd access restrictions). Install on Debian trixie or Ubuntu resolute with:

echo "deb [trusted=yes] https://deb.myguard.nl trixie main" \
  > /etc/apt/sources.list.d/myguard.list
apt update
apt install postfix postfix-ldap postfix-mysql postfix-pcre postfix-pgsql postfix-sqlite

The eilandert/postfix Docker image

For people who don’t want to install Postfix on the host, the eilandert/postfix image on Docker Hub (Debian and Ubuntu variants) wraps the same package in a container that boots in about 400 milliseconds and weighs 277 MB. The Dockerfile installs the myguard Postfix plus its map modules, populates /etc/postfix.orig with the hardened defaults, and runs a bootstrap.sh that copies them into the volume-mounted /etc/postfix on first run. After that, the container respects whatever you put in the volume.

The compose file is essentially:

services:
  postfix:
    image: eilandert/postfix:debian
    container_name: postfix
    restart: always
    ports:
      - 25:25/tcp
      - 587:587/tcp
    volumes:
      - ./config/postfix:/etc/postfix:rw
      - ./data/postfix:/var/lib/postfix:rw
      - /etc/letsencrypt:/etc/letsencrypt:ro
    environment:
      - TZ=Europe/Amsterdam

A few container-specific touches. The image preloads libmimalloc-secure.so via LD_PRELOAD for the security-hardened allocator (you can switch to jemalloc or none via the MALLOC env var). It runs postfix reload in a daily loop in the background so renewed Let’s Encrypt certs get picked up automatically. And it forwards logs either to stdout (which Docker captures) or to a remote syslog if you set SYSLOG_HOST. The whole thing is on the dockerized monorepo at github.com/eilandert/dockerized.

For the full mail-server stack, Postfix plus Dovecot for IMAP, rspamd for filtering, DKIM keys, DMARC reporting, see the Postfix + Dovecot setup guide. It walks the whole pipeline end to end. This article was mostly about what’s new in 3.11 itself; that one is about how to make it actually deliver mail.

Frequently Asked Questions

Does Postfix 3.11 actually require OpenSSL 3.5 for post-quantum TLS?

For X25519MLKEM768 and SecP256r1MLKEM768, yes. OpenSSL 3.5 (April 2025) is the first stable release with hybrid ML-KEM groups in TLS 1.3. Postfix doesn’t carry its own crypto; it asks OpenSSL to negotiate. If the system OpenSSL is older, the PQ group names in tls_eecdh_auto_curves are silently ignored and the handshake falls through to whatever classical curves are left in the list. That’s why the recommended setting puts PQ groups first and classical X25519 / P-256 / P-384 second, older peers degrade gracefully.

Is opportunistic TLS in SMTP secure against active attackers?

No. Opportunistic STARTTLS is downgrade-attackable by anyone who can inject TCP, they strip the STARTTLS response from the EHLO answer and the client falls back to plaintext. The fix is DANE (DNSSEC + TLSA records) or MTA-STS (a published HTTPS policy file). DANE is technically stronger because the TLSA record is signed; MTA-STS is easier to deploy because you don’t need DNSSEC. Postfix supports both. For a public-facing MTA, you want at least one of them active.

What’s the difference between postscreen and smtpd access restrictions?

Postscreen is the front door, it decides whether the connecting IP gets to talk to a real SMTP server at all, based on DNSBL scoring and protocol-violation heuristics. It does all this in one daemon, before smtpd is even involved. Smtpd access restrictions run later, once the connection has cleared postscreen, and operate on the SMTP envelope itself (HELO name, MAIL FROM, RCPT TO). Postscreen is cheaper because it never spins up a per-connection smtpd process for connections it kills; smtpd restrictions can do things postscreen can’t, like reject based on the recipient address. Use both.

Is the eilandert/postfix Docker image production-ready?

It’s what’s running the production mailscreen at myguard.nl, so by that definition yes. It’s a small wrapper around the deb.myguard.nl Postfix package with a bootstrap script that respects volume-mounted config. The image is rebuilt automatically when the underlying package version moves. The main things you bring to it are a real cert (mount /etc/letsencrypt read-only), a real main.cf (mount your config dir), and a milter setup for content filtering (rspamd typically). Don’t run it without those.

Do I need to enable TLSRPT to use the new Postfix?

No. TLSRPT is opt-in for both the sender and the receiver. As a sending MTA, Postfix only emits reports when it sees a recipient domain that publishes a TLSRPT TXT record. As a receiver, you only see reports if you publish the record and run an ingestion pipeline. Most operators ignore TLSRPT entirely and the world keeps spinning. It’s most useful if you’re operating a domain that receives substantial mail volume and you want visibility into how remote MTAs are actually delivering it.

Should I disable Berkeley DB on my Postfix install?

If you’re on Debian trixie or later, the answer is “Debian is going to do it for you”. The Postfix package on deb.myguard.nl already defaults to cdb for lookup tables and lmdb for caches, so the migration is essentially done by the time you install. If you have an existing install with hash: or btree: tables in your main.cf, the Postfix 3.11 NON_BERKELEYDB_README walks the conversion. The short version: run postmap -F cdb:/etc/postfix/transport to rebuild each table in the new format, then update the type prefix in main.cf.

Further reading

• Postfix + Dovecot Mail Server Setup on Debian 12 and 13: the full stack walkthrough, with DKIM, SPF, DMARC, virtual mailboxes and a 10/10 mail-tester score.
• Rspamd Explained: How Modern Spam Filtering Actually Works: what the rspamd milter is doing under the hood (Bayesian, neural, RBLs, URIBLs, OLEFY).
• Docker Hardening: Rootless, Read-only, Distroless: what to do to the eilandert/postfix container if you want to lock it down further.
• postconf(5): the upstream reference for every parameter mentioned in this post.
• RFC 8460 (TLSRPT) and FIPS 203 (ML-KEM) if you want to read the standards instead of trusting my paraphrases.

This is the end-to-end setup guide for the Google Instant Indexing API on WordPress, using the MyGuard Pings module’s Google Indexing subtab. By the end you’ll have a service account, a downloaded JSON key, a verified Search Console ownership grant, and a single test ping returning a clean 200 from indexing.googleapis.com. If you’re here looking for the IndexNow alternative (which actually works for normal blog posts), skip to the FAQ at the bottom, short answer: we ship both, IndexNow is the recommended default, and you should probably enable IndexNow first.

The honest disclaimer up front

Read this once, then we never have to talk about it again.

Google’s own Indexing API quickstart opens with a fence: “Only use the Indexing API to notify Google of JobPosting or BroadcastEvent embedded in a VideoObject.” That’s the entire supported surface. Job listings and livestream events. Nothing else. John Mueller from Google’s Search Relations team has restated this multiple times on Twitter and at office hours. If you submit a URL that isn’t one of those schema types, the API returns 200 OK with a friendly urlNotificationMetadata object, and then nothing happens. The signal is discarded server-side. Google does not promise it will affect crawl scheduling for general content, and they explicitly say it doesn’t.

So why does every SEO plugin ship this feature? Two reasons. One: between roughly 2019 and 2021, the API did have an observable effect on first-crawl latency for non-JobPosting content. That window has closed but the muscle memory hasn’t. Two: even today, a noisy minority of SEOs swear they still see faster discovery. There’s no controlled study, only forum threads. The honest engineer’s take is: it’s free, it’s harmless, the quota is small, the worst case is a no-op. If you have the patience to set it up, set it up. If you don’t, enable IndexNow instead, IndexNow is an open spec, multi-engine (Bing, Yandex, Naver, Seznam), and it actually works for arbitrary content. The MyGuard Pings module enables IndexNow by default; this article is about the Google-specific bit you have to opt into.

What the Google Instant Indexing API WordPress setup actually builds

Before the click-through, it helps to know what we’re assembling. The Google Indexing API doesn’t take a username and password. It uses OAuth 2.0 with a service account, a non-human Google identity you create, give a private RSA key, and authorise to act on your domain. The flow looks like this:

1. Your plugin builds a JSON Web Token (JWT): a short signed payload that says “I am service account X, and I want to do indexing things for the next hour.”
2. It signs that JWT with the private key you downloaded (RS256, that’s RSA-SHA256).
3. It POSTs the signed JWT to Google’s OAuth token endpoint and gets back a short-lived access token (about an hour).
4. It uses that access token as a bearer credential to call https://indexing.googleapis.com/v3/urlNotifications:publish with the URL it wants Google to crawl.

The MyGuard plugin handles steps 1–4 for you. Your job is steps 0a through 0g: creating the service account, downloading the key, granting it ownership in Search Console, pasting the JSON into the plugin. All the cryptographic plumbing is on our side. You’re providing identity.

Step 1, Sign into the Google Cloud Console

Open console.cloud.google.com. Sign in with whichever Google account you want to own this service account, most sysadmins use their main Workspace identity here; some create a dedicated ops@ alias so the indexing project survives staff turnover. Either is fine. The service account itself is what matters, not the human who created it; you can transfer projects between owners later.

If this is your first time in Cloud Console, Google will ask you to accept the terms and pick a country. You’re not signing up for billing, the Indexing API has a free quota of 200 requests/day and doesn’t require a billing account to use at that tier.

Step 2, Create a project

Top bar, the project dropdown (left of the search box). New Project. Name it something boring and self-explanatory. I use wordpress-indexing; you’ll thank yourself in a year when you’ve forgotten what untitled-project-7 is supposed to do. Leave the organisation field as-is (it’ll default to your personal account if you’re not in a Workspace org). Click Create and wait ten seconds for the spinner.

Once it’s created, make sure the project dropdown is showing your new project. This is the single most common mistake in this entire procedure: people enable APIs and create service accounts in the wrong project, then wonder why nothing works. Check the top bar. The active project name appears there. It should say wordpress-indexing (or whatever you called it).

Step 3, Enable the Indexing API

Hamburger menu (top-left) → APIs & Services → Library. In the search box, type indexing. The first result will be Web Search Indexing API (or just Indexing API, the rename has been ongoing). Click it. Hit the big blue Enable button. It’ll think for five seconds and then drop you on the API’s dashboard.

If you skip this step, every API call later returns the gloriously specific error “Indexing API has not been used in project wordpress-indexing before or it is disabled. Enable it by visiting…”, followed by a URL that takes you right back to this page. Google’s error messages here are unusually good. Trust them.

Step 4, Create the service account

Hamburger menu → IAM & Admin → Service Accounts. Click + Create Service Account at the top. You’ll see a three-step form.

• Service account name: something descriptive. wp-indexing-bot works. This becomes the prefix of the auto-generated email: you’ll end up with something like wp-indexing-bot@wordpress-indexing.iam.gserviceaccount.com.
• Service account ID: Google fills it in from the name. Leave it.
• Description: optional. Write “Pings Google Indexing API for new WordPress posts on deb.example.com” or whatever helps future-you.

Click Create and Continue. The next step asks you to grant this service account access to project. Skip it. The Indexing API does not authorise via project-level IAM roles; it authorises via Search Console ownership (we’ll do that in step 6). Granting a project role here is harmless but unnecessary, and granting Owner on the project is actively dangerous, it gives the service account power over your entire Google Cloud project, not just indexing. Skip the role assignment, click Continue, then Done.

You’ll land back on the Service Accounts list with one new entry. Copy the email address (the long ...gserviceaccount.com string). You’ll paste it into Search Console in step 6. Keep it on the clipboard or jot it down.

Step 5, Generate and download the JSON key

Click the service account’s email in the list. You’ll land on its details page. Top tabs: Details, Permissions, Keys, Metrics, Logs. Open Keys.

Add Key → Create new key. A modal pops up asking JSON or P12. JSON. Always JSON. P12 is a legacy format (PKCS#12, a 1996 vintage container originally for client TLS certs) that the modern Google SDKs still support but which nobody on the WordPress side wants to deal with. Click Create.

Your browser will download a file. The filename is something hideous like wordpress-indexing-a1b2c3d4e5f6.json. Open it in a text editor. You’ll see this:

{
  "type": "service_account",
  "project_id": "wordpress-indexing",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...lots of base64...\n-----END PRIVATE KEY-----\n",
  "client_email": "wp-indexing-bot@wordpress-indexing.iam.gserviceaccount.com",
  "client_id": "12345...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/wp-indexing-bot%40wordpress-indexing.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

This file is now a private RSA key in a JSON wrapper. Treat it like an SSH private key. Anyone holding this can ping the Google Indexing API as you, until you revoke it from the same Keys tab. Do not commit it to git. Do not paste it into a Slack channel. Do not email it to yourself unencrypted. If it leaks, go straight back to the Keys tab, delete that key entry, and generate a new one, there’s no PEM-passphrase concept, no rate-limit-the-blast-radius option, just “key exists” vs “key doesn’t exist”.

If you’re the kind of paranoid that I am, save the key into something like Bitwarden / self-hosted Vaultwarden as a “secure note” once it’s pasted into the plugin, then shred the local copy:

shred -u ~/Downloads/wordpress-indexing-a1b2c3d4e5f6.json

The key is now in WordPress’s wp_options table, which is approximately as safe as the rest of your WordPress install. That’s a real consideration, if a third party gains read access to your database (SQL injection, misconfigured backup, a stolen wp-config.php) they get this key. Plan accordingly. If you keep encrypted DB backups off-site, encrypt them. Don’t keep plain-text DB dumps lying around in /tmp after a debugging session.

Step 6, Grant Search Console ownership

This is the step nobody explains properly and where most people fail with a 403.

The Indexing API doesn’t trust the service account’s existence alone. It checks, on every request, whether that service account is listed as an Owner of the target site in Google Search Console. Lesser roles (Full user, Restricted user) return 403. Must be Owner. This is unusual, Google services normally accept multiple permission levels, but the Indexing API was built when domain ownership was the only model that made sense for “may I tell you to re-crawl this”.

Go to search.google.com/search-console. Pick the property for the domain you want to ping. If you don’t have one yet, add it now (the domain-property type is preferred; it covers all subdomains and protocols, but requires a DNS TXT record to verify). Take that detour, come back, then continue.

With the property selected, click the gear icon (Settings) in the left sidebar → Users and permissions. You’ll see yourself listed as Owner. Click Add user in the top right.

• Email address: paste the client_email from the JSON file. The full wp-indexing-bot@wordpress-indexing.iam.gserviceaccount.com address. Google will not complain that it’s not a human Gmail; it accepts service-account emails here.
• Permission: Owner. Not Full user. Not Restricted user. Owner.

Click Add. The service account now appears in the Users list with the Owner badge. From this moment, the API will accept publish requests for URLs on this domain from this service account.

If you run multiple WordPress sites and want to ping all of them with one service account, repeat this Search Console step for each domain. The same service account can be Owner on as many properties as you want, there’s no per-domain key needed. The downside is that a leak gives the attacker indexing rights across all those domains, so if your blast radius matters, use one service account per property.

Step 7, Paste the JSON into MyGuard

In WordPress admin: MyGuard → Pings → Google Indexing. You’ll see two ways to provide the key:

• Paste it into the big monospaced textarea. The whole JSON, opening brace to closing brace. The plugin’s textarea is wide enough to show the structure without horizontal scrolling.
• Or click Browse next to “Or upload the .json file” and pick the file Google downloaded. The browser reads the file in JS (it never leaves your machine until you hit Save) and pastes it into the textarea for you. This is usually the more reliable path because it avoids the next paragraph’s failure mode.

The number-one paste failure is mangled newlines in the private_key field. The JSON file uses \n as a literal two-character escape inside the string. If you copy the JSON out of a terminal that does line-wrapping, or paste through an editor that “helpfully” normalises whitespace, those escapes can turn into actual newlines, breaking the JSON parse. The file upload method bypasses this; if you must paste, paste from a real text editor (VS Code, gedit, Notepad++) rather than from a terminal that’s been word-wrapping.

Step 8, Save and verify

Click Save. The plugin runs a server-side json_decode() on the field, validates that type == "service_account" and that client_email, private_key, and token_uri are all present. If the parse fails, you’ll see a red admin notice “Saved, but the pasted JSON failed to parse as a valid service-account key. The previous key (if any) was kept.” The save handler deliberately keeps your old (working) key in that case, so a fat-finger paste doesn’t lock you out of your previously-working integration.

If the parse succeeds, you’ll see a green notice showing the parsed client_email and project_id. That’s your confirmation that the plugin can actually use the key. From this point on, every ping the plugin sends will arrive at Google’s OAuth endpoint as a JWT signed with the private_key field of this JSON.

Step 9, Test now

Click Test now (uses 1 quota). The plugin picks the most recent published post (of the post types you’ve selected, defaults to Posts), signs a JWT with your private key, exchanges it for an access token at Google’s OAuth endpoint, then POSTs a URL_UPDATED notification for that post’s permalink. The expected result is HTTP 200 with a JSON body containing urlNotificationMetadata.

If you want to verify what’s actually flying across the wire, the same call from the shell looks like this, useful for debugging, for understanding, or for satisfying the urge to see the bits move:

# With $ACCESS_TOKEN obtained from the OAuth dance (the plugin does this for you):
curl -sS -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/your-post-slug/","type":"URL_UPDATED"}' \
  https://indexing.googleapis.com/v3/urlNotifications:publish

On success Google replies with the timestamp of your notification, proof that the request was accepted into their indexing queue. Whether they act on it for non-JobPosting content is the other question, but the API accepted you. That counts as setup-complete.

Step 10, Flip the switch

Toggle Enable on, hit Save once more. The plugin now adds a Google Indexing call to every drain tick: every time a queued post leaves the queue (whether queued by the auto-trigger on publish/update or shoved in manually from the Manual subtab), the plugin fires the Indexing API alongside whatever other endpoints you have enabled. One call per post. Subject to the 200/day quota, which the subtab shows you as a live meter.

That meter resets at 00:00 UTC. Google’s quotas are wall-clock UTC, not your local time, not your WordPress timezone. If you publish a flurry of posts late on a UTC-day boundary, half might miss the day-N quota and end up firing on day-N+1, the queue tolerates that gracefully (it just respects the per-endpoint 1/hour rate limit, separately from the daily quota).

What 200 requests/day actually means

The default project quota is 200 urlNotifications:publish requests per day. That sounds generous, and for most personal blogs it is. The math: you’d have to publish or substantively update a post every seven minutes for sixteen hours straight to exhaust it. If you do, congratulations, you’re a content farm and Google has other concerns about you.

Google publishes a quota-increase request form. It’s gated by use case, they want to see that you’re a legitimate JobPosting or BroadcastEvent publisher with a track record. Requesting more than 200/day for general blog content is almost never granted. If your real use case is a job board, request away; if not, treat 200 as a hard ceiling and design around it (which mostly means: don’t ping every trivial edit, only meaningful publishes, which the plugin already does by gating on post_modified advancing and on actual content changes).

Optional but recommended: verified quota via Cloud Monitoring

The plugin tracks your daily usage in two ways. By default it just increments a local counter every time it gets a 2xx back from the Indexing API. That works but it can drift: a manual Test now retry, a quota you spent from another script outside WordPress, a server-side rate limit you weren’t tracking, the local number falls out of sync with what Google actually thinks. There’s a fix: ask Google.

Google exposes per-project Indexing API usage via the Cloud Monitoring API as a quota/allocation/usage time-series metric. The plugin can query it directly using the same service-account JSON you already pasted in, it just needs a second OAuth scope (monitoring.read) and two extra setup steps in Cloud Console. Once it works, the subtab’s Daily quota row swaps from “local counter only” to “✓ verified via Cloud Monitoring N minutes ago” and the number you see is the real per-project total Google has registered for today.

Two steps:

1. Enable the Cloud Monitoring API in the same project that owns the service account. Cloud Console → APIs & Services → Library → search monitoring → pick Cloud Monitoring API → Enable. Same drill as step 3 above.
2. Grant the service account the roles/monitoring.viewer role. Cloud Console → IAM & Admin → IAM → find your service account’s row (it’ll show as wp-indexing-bot@iam.gserviceaccount.com: yes, the same one) → click the pencil → Add another role → Monitoring Viewer → Save. This is read-only access to your project’s monitoring data; it can’t write metrics or change anything.

Refresh the Google Indexing subtab. If both steps worked, the meter changes to the verified-count display with a green checkmark and the timestamp of the last fetch. If something’s off, the subtab shows the literal error message from Google’s Monitoring API inline, usually either “Cloud Monitoring API has not been used in project X” (step 1 missing) or “Permission denied on resource” (step 2 missing or applied to the wrong account). The plugin caches the verified count for 5 minutes so admin page loads stay snappy and you don’t burn Monitoring API quota; that’s also why the timestamp shows “N minutes ago” rather than “right now”.

Setting this up is optional. The plugin works without it, the local counter is a reasonable proxy. But if you care about the difference between “200 calls I think I made” and “200 calls Google actually counted”, spend the five minutes.

Troubleshooting

Four failure modes account for almost every problem people have with this API.

• HTTP 403 Permission denied. The service account isn’t an Owner of the target domain in Search Console. Re-do step 6. The error text usually includes the domain it’s checking against: sanity-check that it matches the URL you’re submitting (you can’t ping example.com if you’re Owner of www.example.com only, because Search Console URL-properties are exact).
• HTTP 401 / invalid_grant. The JSON paste corrupted the private_key. Almost always a newline issue: see step 7. Re-upload via the file input.
• HTTP 429 Quota exceeded. You’ve spent the 200 for today. The plugin’s quota meter on the subtab tells you exactly how many you’ve used. Wait until 00:00 UTC. Don’t disable the toggle in panic: the next reset will sort it.
• "Indexing API has not been used in project X before or it is disabled". You skipped step 3. Or you enabled it in a different project than the one your service account lives in. Cloud Console → APIs & Services → Library, search indexing, click Enable. Make sure the project dropdown matches the service account’s project (the project_id field in your JSON).

For everything else, the plugin’s History subtab shows the full last-7-days response log including Google’s error message body, which tells you precisely what’s wrong. There’s a per-endpoint summary too, so if Google Indexing is consistently failing while every other endpoint is succeeding, the row colours make it obvious without scrolling.

When you should use IndexNow instead (or alongside)

IndexNow is what you actually want for normal blog posts. It’s an open spec, Microsoft started it, Bing implemented it first, and now Yandex, Naver, and Seznam all participate. One ping fans out to all of them. It works for any content type, no JobPosting fence. The MyGuard plugin enables IndexNow by default with all four direct endpoints (Bing, Yandex, Naver, Seznam) plus the central api.indexnow.org fanout. The only configuration required is generating an IndexNow key, which the plugin does at the click of a button, and serving it from /{key}.txt at your site root, which the plugin also does automatically with an init hook.

Google doesn’t participate in IndexNow. Officially they “evaluated” it and decided not to join. Unofficially, IndexNow telemetry suggests the participating engines hit roughly the search-volume sweet spot you actually care about outside the US, Naver dominates Korea, Yandex dominates Russia, Seznam is the default search engine for tens of millions of Czechs and Slovaks, and Bing’s slice of the global pie has crept past 5% in 2026 thanks to its tight ChatGPT integration. Pinging those four covers a real and growing fraction of the planet.

The pragmatic stack: enable IndexNow for everything, enable Google Indexing as a best-effort opt-in (especially if you publish job listings or livestream content), and let Google’s normal crawler find your other posts via your sitemap. The plugin’s Settings subtab has IndexNow grouped at the top with its key field; the Endpoints subtab has the dozen-or-so still-living legacy XML-RPC blog ping services for the truly old-school. Use what helps; ignore what doesn’t.

Behind the curtain, what the JWT actually contains

For anyone curious, here’s the assertion the plugin builds and signs every hour to refresh its access token. The header is trivial, algorithm and type:

{"alg":"RS256","typ":"JWT"}

The claim is where the interesting bits live:

{
  "iss":   "wp-indexing-bot@wordpress-indexing.iam.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/indexing",
  "aud":   "https://oauth2.googleapis.com/token",
  "iat":   1779713000,
  "exp":   1779716600
}

iss is the issuer, your service account email. scope is the OAuth scope being requested; the indexing scope is the minimum required, no broader Google API access is granted. aud is the audience, Google’s token endpoint, which is what verifies the signature. iat and exp are issued-at and expires-at Unix timestamps; Google accepts a maximum of one hour between them. The plugin caches the resulting access token for 50 minutes (a 10-minute clock-skew margin) so the OAuth round-trip only happens roughly once an hour per service account.

The signature is RS256 over base64url(header) + "." + base64url(claim), computed with the private key. PHP’s openssl_sign($input, $sig, $private_key, OPENSSL_ALGO_SHA256) does the cryptographic work in a single call. The whole signed JWT, header, claim, signature, dot-separated, base64url-encoded, gets POSTed as the assertion form parameter to https://oauth2.googleapis.com/token with grant type urn:ietf:params:oauth:grant-type:jwt-bearer. Google returns a normal OAuth response: access_token, expires_in, token_type. That access token then gets reused for every Indexing call until it expires.

None of which you need to know to use the plugin. But if you’re the kind of person who reads a how-to all the way to the end, you’re the kind of person who wants to know what’s actually happening, and the kind of person who’d notice if I left it out.

FAQ

Related posts

• Database Boost: Free WordPress Database Optimization Plugin, the other half of the MyGuard WordPress stack: scheduled cleanup, repair, and index analysis for the same WP install you just wired into Google.
• Self-Hosted Password Manager with Vaultwarden: where to actually store that JSON service-account key after you’ve pasted it into WordPress and shredded the local copy.
• myguard Debian/Ubuntu Repository: the apt repository the MyGuard plugin ships from. apt install wp-myguard after adding the repo is the only thing you need to get this article’s plugin onto a server.
• How to Add the myguard APT Repository: three commands and a GPG key, and you’re set up to receive plugin updates the same way you receive nginx updates.

This walkthrough is the full self-hosting aptly recipe. We’ll install aptly on Debian or Ubuntu, create a repository, import some .debs, sign them properly, publish to a filesystem endpoint, serve it through NGINX, set the clients up correctly (including the modern deb822 sources format), and finish with a cron-driven snapshot rotation that keeps history without filling the disk. By the end you’ll have something apt update trusts and you control top to bottom.

Why self-hosting aptly (and not reprepro, dak, or just a folder of .debs)

People who’ve been around Debian a while will reach for reprepro on instinct. It works. It’s older. It’s in main. It’s also brittle in ways that bite you the third time you do anything non-trivial, like republishing after a rollback, or running parallel suites for testing/stable, or maintaining snapshots you can pin to. Reprepro’s mental model is “one big mutable archive”. Aptly’s is closer to git: you have repositories (mutable working sets), you take snapshots (immutable, named points in time), and you publish snapshots (or repos) to endpoints (filesystem or S3). You can keep three months of nightly snapshots, publish only the ones you want, and roll back a publish in seconds.

Dak (the Debian Archive Kit) is the other option, and it’s what the actual Debian project uses. It’s also a beast, designed for hundreds of mirrors, an army of FTP-masters, and a complicated NEW queue. For self-hosters, it’s wildly overkill. You don’t want dak unless you are, in fact, becoming a distribution.

“Just put the .debs in a folder and serve them” is the joke answer that almost works. apt won’t index a flat folder; it needs Packages, Packages.gz, Release, Release.gpg, and InRelease files with the right hashes and a valid signature. You could generate those by hand with dpkg-scanpackages + apt-ftparchive + gpg --clearsign, and historically lots of small shops did. It’s about forty lines of shell that you’ll get wrong subtly until something breaks two months later. Aptly is that script done properly, with a state database and a publish workflow on top.

The short version: aptly is the right answer for one to ten thousand packages, one to ten architectures, and a single admin (or small team). Above that you’re probably looking at Pulp or hosted offerings. Below that you’re overengineering.

Self-hosting aptly: installing it on Debian or Ubuntu

The version of aptly in the Debian/Ubuntu archive lags upstream by years (1.5.x at the time of writing, versus upstream 1.6.x). For a host you’re going to live with, install upstream’s apt repo:

# Trust the upstream signing key (modern signed-by pattern, no apt-key)
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://www.aptly.info/pubkey.txt | \
  sudo gpg --dearmor -o /etc/apt/keyrings/aptly.gpg

# Add the repo (deb822 format, the modern one)
sudo tee /etc/apt/sources.list.d/aptly.sources >/dev/null <<'EOF'
Types: deb
URIs: http://repo.aptly.info/
Suites: squeeze
Components: main
Signed-By: /etc/apt/keyrings/aptly.gpg
EOF

sudo apt update
sudo apt install aptly gnupg2

Yes, the suite is called squeeze even on bookworm or noble, upstream just never renamed it. It’s fine; aptly itself is a static Go binary that doesn’t care about distro versions. Verify:

aptly version
# expect aptly version 1.6.x

Aptly’s state lives in ~/.aptly/ by default. For a server install, you almost certainly want it elsewhere, a dedicated mount with room to grow. Create ~/.aptly.conf (or pass -config= on every command, which gets tedious):

{
  "rootDir": "/srv/aptly",
  "downloadConcurrency": 8,
  "downloadSpeedLimit": 0,
  "architectures": ["amd64", "arm64"],
  "dependencyFollowSuggests": false,
  "dependencyFollowRecommends": false,
  "dependencyFollowAllVariants": false,
  "dependencyFollowSource": false,
  "gpgDisableSign": false,
  "gpgDisableVerify": false,
  "gpgProvider": "gpg",
  "downloadSourcePackages": false
}

The rootDir matters more than it looks, and there’s a footgun here we’ll come back to in the gotchas section. For now, give it its own LVM volume or ZFS dataset if you can. Packages are small but they accumulate.

Generate a signing key

An unsigned APT repository will work on the client only with [trusted=yes] flags everywhere, which is the apt equivalent of disabling TLS verification. Don’t. Generate a proper GPG signing key:

gpg --batch --gen-key <<'EOF'
%no-protection
Key-Type: RSA
Key-Length: 4096
Subkey-Type: RSA
Subkey-Length: 4096
Name-Real: My APT Repo Signer
Name-Email: apt@example.com
Expire-Date: 5y
%commit
EOF

The %no-protection means no passphrase, which is what you want for an unattended signing key on a build server. If that makes you nervous: it should, a little, but it’s the same trade-off every CI system makes. Lock down the home directory (chmod 700 ~/.gnupg) and the key file inside it (chmod 600), and keep that machine off the public internet for SSH if you can.

Export the public key for clients to install:

gpg --armor --export apt@example.com > /srv/aptly/public/pubkey.asc
# Also useful for older clients that want a binary keyring file:
gpg --export apt@example.com > /srv/aptly/public/pubkey.gpg

The /srv/aptly/public/ path is whatever aptly will publish into, we’ll wire it up in a moment. Clients install this key into /etc/apt/keyrings/your-repo.gpg and point at it with Signed-By: in their sources file. Modern, no global trust pollution.

Create a repo, import .debs, snapshot, publish

The aptly workflow has four verbs you actually use day-to-day: repo, snapshot, publish, and db cleanup. Walk through it once and you’ve got the muscle memory for life.

# 1. Create a repository
aptly repo create -distribution=bookworm -component=main myrepo-bookworm

# 2. Import .deb files
aptly repo add myrepo-bookworm /path/to/build/output/*.deb

# 3. Snapshot it (immutable named point-in-time)
aptly snapshot create myrepo-bookworm-$(date +%Y%m%d) from repo myrepo-bookworm

# 4. Publish the snapshot to a filesystem endpoint
aptly publish snapshot \
  -distribution=bookworm \
  -architectures=amd64,arm64 \
  -gpg-key=apt@example.com \
  myrepo-bookworm-$(date +%Y%m%d)

That last command does the real work: it writes Packages, Packages.gz, Packages.xz, Release, Release.gpg, InRelease, and a pool/ directory with the actual .deb files (hardlinked, not copied, disk-efficient if your filesystem supports it) into $rootDir/public/dists/bookworm/ and $rootDir/public/pool/main/. The Release.gpg and InRelease are GPG-signed with your key. APT clients fetch InRelease first, verify the signature, then trust the hashes inside it to verify every other file. Standard chain.

To update the repo later: add new .debs with aptly repo add, take a new snapshot, then switch the published distribution to the new snapshot:

aptly publish switch bookworm myrepo-bookworm-$(date +%Y%m%d)

This is the magic that makes aptly nicer than reprepro: a switch is atomic to the client (one HTTP request to InRelease sees old, the next sees new), and if the new snapshot breaks something you can publish switch back to yesterday’s snapshot in two seconds and nothing on the client side is the wiser.

Serve it with NGINX

Aptly only generates files. It does not serve HTTP. That’s NGINX’s job, and the config is mercifully short:

server {
    listen 80;
    listen [::]:80;
    server_name apt.example.com;

    root /srv/aptly/public;

    # APT clients want correct MIME types; defaults are fine for .gz/.xz
    # but explicitly state .deb so they don't get served as text/html
    types {
        application/x-debian-package deb;
        application/pgp-signature     gpg sig asc;
        text/plain                    Release InRelease;
    }

    # Directory listings are optional; many people leave them on
    # for human browsability. Off is safer for production.
    autoindex off;

    # Long cache for pool files (they're content-addressed, never change)
    location /pool/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Short cache for dists/ (Release/InRelease/Packages change)
    location /dists/ {
        expires 5m;
        add_header Cache-Control "public, must-revalidate";
    }

    access_log /var/log/nginx/apt.access.log;
    error_log  /var/log/nginx/apt.error.log;
}

That’s it. No PHP, no Python, no database. NGINX serves static files; APT clients consume them. Add a TLS listener if you want HTTPS (and you do, even for a public-read repo, at minimum it stops corporate proxies from caching old InRelease files at random). If the repo is private, slap basic-auth on top:

auth_basic           "apt repo";
auth_basic_user_file /etc/nginx/.htpasswd_apt;

Then on the client, embed credentials in the URI (https://user:pass@apt.example.com/) or use /etc/apt/auth.conf.d/example.conf with machine apt.example.com login user password pass.

Client setup, the modern way

For years everyone wrote one-line entries into /etc/apt/sources.list and called it done. APT now prefers the deb822 format in /etc/apt/sources.list.d/. It’s more verbose, more readable, and lets you put Signed-By: directly in the source, no more polluting the global apt trust store.

Client install in three commands:

# 1. Install the repo's public key as a binary keyring
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://apt.example.com/pubkey.asc \
  -o /etc/apt/keyrings/example-repo.asc

# 2. Write a deb822-format source file
sudo tee /etc/apt/sources.list.d/example.sources >/dev/null <<'EOF'
Types: deb
URIs: https://apt.example.com/
Suites: bookworm
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/example-repo.asc
EOF

# 3. Use it
sudo apt update
sudo apt install your-package

The Signed-By: binding is what stops a compromised different repo from injecting packages signed with a different key. Each repo’s signature is scoped to that repo only. Modern APT enforces this strictly. Don’t use the deprecated apt-key add path on any client newer than Debian 11 or Ubuntu 22.04, it’ll work, with warnings, but it adds your key to global trust which is exactly what we’re trying to avoid.

This is also how our own how-to-use page tells clients to install our repo. Same pattern. Same security model.

The shared-rootDir trap (and other gotchas)

This is where our own scar tissue earns its keep. Every aptly endpoint you publish lives under the same $rootDir/public/ directory. If you have, say, a primary endpoint serving deb.example.com and a secondary endpoint serving internal.example.com from the same aptly install, they share the publish tree. A aptly publish drop on one endpoint can, and will, wipe files used by the other endpoint, because the cleanup logic walks the shared pool/ and removes anything not referenced by a currently-published snapshot. We learned this the hard way: a drop on the secondary endpoint took out a chunk of packages on the primary. Recovery was a full republish from snapshots. Lesson: if you run multiple aptly endpoints, give each one its own rootDir (separate aptly state directory), even if it costs you some disk to duplicate the pool. Or accept that all your endpoints are coupled and never publish drop without thinking hard.

Other ones to watch:

• Snapshot accumulation eats disk. Every aptly snapshot create ref-keeps the .debs it points at, even after you’ve stopped publishing them. aptly db cleanup removes orphans (.debs no snapshot references). Run it weekly or you’ll find /srv/aptly/pool/ at 200 GB of old NGINX nightlies you forgot about.
• GPG agent and unattended signing. Modern GPG insists on talking to gpg-agent, which insists on a TTY. On a headless server, set GPG_TTY=$(tty) in the cron environment or use gpg --pinentry-mode loopback. If your aptly publish runs hang with no output, this is almost always why.
• Architecture mismatch. If your aptly.conf says architectures: ["amd64"] and you add an arm64 .deb, aptly silently drops it. Always include every arch you build for.
• The InRelease + Release + Release.gpg trio. Older clients want Release and Release.gpg (detached signature). Newer clients want InRelease (clear-signed combined file). Aptly writes both by default; if your NGINX is doing aggressive caching, make sure all three are served fresh, not just one.
• Time skew breaks signature verification. A signed InRelease has a Valid-Until field. If your server clock is wrong, you can sign files that are already expired. systemd-timesyncd is your friend.

Automation: cron, snapshot rotation, signal-safe

The whole point of running your own repo is to make publishing trivial. A working build-and-publish cron is short:

#!/bin/bash
# /usr/local/bin/apt-publish-nightly
set -euo pipefail

export GNUPGHOME=/srv/aptly/.gnupg
export GPG_TTY=$(tty || echo /dev/null)
SUITE=bookworm
REPO=myrepo-bookworm
SNAP="${REPO}-$(date +%Y%m%d-%H%M)"

# 1. Add any new .debs the build system dropped
aptly repo add -force-replace "$REPO" /srv/build/output/*.deb

# 2. New snapshot
aptly snapshot create "$SNAP" from repo "$REPO"

# 3. Atomically switch the published suite to the new snapshot
aptly publish switch -gpg-key=apt@example.com "$SUITE" "$SNAP"

# 4. Drop snapshots older than 30 days
aptly snapshot list -raw | grep "^${REPO}-" | while read -r s; do
  d=$(echo "$s" | sed -E "s/^${REPO}-([0-9]{8}).*/\1/")
  age_days=$(( ( $(date +%s) - $(date -d "$d" +%s) ) / 86400 ))
  if [ "$age_days" -gt 30 ]; then
    aptly snapshot drop "$s" || true
  fi
done

# 5. Garbage-collect orphaned .debs
aptly db cleanup

Drop it in cron with 15 2 * * * /usr/local/bin/apt-publish-nightly >> /var/log/apt-publish.log 2>&1 and you have a self-rotating, signed, snapshotted APT repository that needs zero attention until something genuinely breaks. The -force-replace on repo add lets you re-add a .deb with the same version (useful if you rebuilt to fix a packaging-only bug); without it, aptly refuses, which is also a defensible default.

For the truly paranoid: pipe the publish step through a wrapper that publishes to a staging endpoint first, runs apt-get -s install against it from a test container, and only switches the production endpoint if the dry-run succeeds. This is what our build farm does for every nightly. The whole pipeline is <200 lines of shell.

FAQ

Related reading

• How to Add the myguard APT Repository (Debian & Ubuntu): the deb822 client-side recipe, exactly as described above, applied to our own repo.
• myguard Debian/Ubuntu Repository: what a fully-populated aptly-hosted repo looks like in production, with NGINX, Angie, and the full module set.
• Where To Find Us: All Our Repos, Docker Images & GitHub Projects, the full topology of how our build farm publishes to multiple endpoints (and how we avoid the shared-rootDir trap).
• Packages: the complete catalogue served from the setup described in this article.

This is the real-world HTTP/3 setup. The one that works in production. We’ll cover what QUIC actually is and why it matters, what HTTP/3 support looks like in mainline NGINX versus Angie versus our deb.myguard.nl builds, a complete listen-block you can paste, the handful of sysctl knobs that turn it from “kinda works” into “fast”, and the gotchas that have eaten more weekends than I’d like to admit. Getting HTTP/3 on NGINX into production is mostly about the parts the wiki leaves out.

What HTTP/3 and QUIC actually are (HTTP/3 on NGINX)

HTTP/3 on NGINX is HTTP/2’s semantics riding on top of QUIC instead of TCP, served by an NGINX build that knows what to do with it. That’s the whole story, told fast. Same requests, same responses, same headers, same streams. The transport underneath is different, and it’s the transport that buys you everything interesting.

QUIC (Quick UDP Internet Connections, because the IETF likes a recursive acronym) is a transport protocol layered on UDP that does what TCP+TLS used to do, but in one handshake instead of three. It was born at Google around 2012 as gQUIC, got dragged into the IETF, mutated for half a decade, and finally shipped as RFC 9000 in 2021. HTTP/3 is RFC 9114. Both stabilised years ago. The reason your stack might not speak it yet is purely sociological: the kernel folks, the load-balancer folks, the firewall folks, and the WAF folks all had to update their stuff, and that takes time.

The headline wins:

• One handshake instead of two. A normal HTTPS connection over TCP costs you one round-trip to set up the TCP socket, then another for TLS. QUIC folds TLS 1.3 into the transport itself. First connection: 1-RTT. Resumed connection: 0-RTT (you can send the GET in the very first packet). Half the time-to-first-byte on a cold connection, basically for free.
• Head-of-line blocking is gone. HTTP/2 multiplexed streams over a single TCP connection, which sounded great until one packet got dropped and every stream stalled waiting for the retransmit. QUIC moves stream multiplexing below the loss-recovery layer, so a lost packet only stalls the stream that packet belonged to. The other streams keep flowing. This is the single biggest deal for anyone serving lots of small assets.
• Connection migration. A QUIC connection is identified by a connection ID, not by the four-tuple of IPs and ports. Your phone leaves wifi, switches to 5G, gets a new IP: the connection keeps going. No reconnect. No re-handshake. Streaming video doesn’t even pause.
• Encryption is mandatory and it’s all of it. QUIC encrypts the transport headers, not just the payload. Middleboxes can’t peek at sequence numbers, can’t rewrite flags, can’t fingerprint the way they used to. This is also why some “DPI-aware” firewalls hate it.

The trade-off: it’s UDP. Some networks throttle UDP, some firewall it entirely, and CPU usage per byte is higher than TCP because everything happens in userspace. (There’s kernel offload work happening, GSO, GRO, the io_uring stuff, but we’ll get to that.)

HTTP/3 support: mainline NGINX vs Angie vs our packages

This is where the documentation gets confusing because three timelines are running in parallel.

Mainline NGINX shipped experimental QUIC and HTTP/3 in 1.25.0 (May 2023), and marked it production-ready in 1.25.3 (October 2023). As of 2026, every NGINX 1.27.x and 1.29.x mainline release has it built in. You don’t need a separate nginx-quic branch any more, that fork was merged into mainline and archived. Stable branch (1.26.x, 1.28.x) also has it; F5 backported once they decided the dust had settled.

What you do still need: an OpenSSL with QUIC API support. Mainline NGINX uses OpenSSL’s compat shim, which works but doesn’t expose every TLS feature. For 0-RTT and full ALPN control you want one of quictls, BoringSSL, AWS-LC, or OpenSSL 3.5+ (which finally landed proper QUIC server-side API). The ./configure dance has been written about a thousand times; the short version is --with-http_v3_module --with-cc-opt=-I/path/to/quictls/include --with-ld-opt=-L/path/to/quictls/lib.

Angie (the fork from former NGINX-core devs after the F5 acquisition) has had HTTP/3 since the very first release and treats it as a first-class feature. The directives are mostly compatible with mainline NGINX’s, plus a couple of Angie-specific ones (quic_active_connection_id_limit, finer-grained quic_log). Angie also has built-in support for live monitoring of QUIC connections via its /status endpoint, which is genuinely nice when you’re debugging.

Our deb.myguard.nl NGINX packages ship with HTTP/3 enabled by default, linked against quictls, and bundled with the full compression stack and the rest of our dynamic module set. Same goes for our Angie packages. You don’t need to compile anything; apt install nginx from our repo and the binary already speaks h3. The packages also bundle the BoringSSL link variant if you’d rather have that (it tends to be slightly faster on the QUIC hot path, at the cost of dropping a few legacy TLS features almost nobody uses).

A practical heuristic: if you’re already running NGINX 1.25.3+ from any reputable source, you have HTTP/3. The question isn’t “do I have it” but “is the config right and is the network plumbing in shape”.

The minimum viable HTTP/3 listen block

Here’s a config that actually works. Drop it in your server block alongside your existing HTTPS listen:

server {
    # Existing HTTP/1.1 + HTTP/2 over TCP
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;

    # HTTP/3 over QUIC (UDP)
    listen 443 quic reuseport;
    listen [::]:443 quic reuseport;

    # Same TLS config as your existing HTTPS
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols       TLSv1.3;
    ssl_early_data      on;            # enables 0-RTT for resumed sessions

    # Tell browsers HTTP/3 is available on this host
    add_header Alt-Svc 'h3=":443"; ma=86400' always;

    # Optional: hint that early data is being served
    add_header X-Early-Data $ssl_early_data always;

    server_name example.com;
    root /var/www/example.com;
}

A few things worth pointing out, because they trip people up every time:

reuseport is not optional, it’s the whole point. Without it, every QUIC packet gets dispatched through a single listening socket and then handed to a worker, which murders multi-core throughput because that one socket becomes a contention hot spot. With reuseport, each worker gets its own UDP socket bound to the same port via SO_REUSEPORT, and the kernel hashes incoming packets across them. On a 16-core box, this is the difference between 4 Gbps and 40 Gbps.

ssl_early_data on enables 0-RTT. Resumed connections can send the HTTP request in the very first QUIC packet. This is brilliant for repeat visitors but it has a footgun: 0-RTT data is replayable, which means it must be safe to replay. GET requests to idempotent endpoints, fine. POST to /transfer-money, not fine. Most apps don’t care because browsers only send GETs in 0-RTT, but if you have weird shaped traffic, check.

The Alt-Svc header is how a browser learns your server speaks HTTP/3. The browser hits you over TCP+HTTP/2 first, sees the header, remembers it for ma seconds (max-age, 86400 is one day), and on the next request it tries QUIC first. If your alt-svc header doesn’t reach the browser, no client will ever speak HTTP/3 to you, no matter how perfectly your QUIC config works. This is the most common “why isn’t this working” cause, and we’ll come back to it.

Tuning that actually matters

The default UDP receive buffer on a Linux box is somewhere between 200 KB and 4 MB depending on distribution. For an HTTP/3 server doing real traffic, that’s tiny. Bursts of incoming packets overflow the socket buffer, the kernel drops them, QUIC sees loss, slams the congestion window shut, and your throughput collapses to gigabit-modem speeds. Fix it:

# /etc/sysctl.d/99-quic.conf
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.core.rmem_default = 2097152
net.core.wmem_default = 2097152
net.core.netdev_max_backlog = 5000
# Then: sysctl --system

You also need NGINX to actually ask the kernel for those bigger buffers. The listen directive has a rcvbuf / sndbuf param:

listen 443 quic reuseport rcvbuf=2m sndbuf=2m;

Without those, NGINX uses the default and you’ve sysctl’d for nothing.

Other QUIC-specific NGINX directives worth knowing about:

• quic_retry on;: turns on the QUIC retry mechanism, which makes the client prove its source address before you allocate state. This is your DDoS defence; without it, a single-packet UDP source-spoofing attack can make your server allocate state for millions of fake “connections”. Cost: one extra round-trip on the first connection. Worth it.
• quic_gso on;: Generic Segmentation Offload. The kernel sends multiple UDP segments as a single sendmsg() call and lets the NIC slice them up. On any reasonable NIC from the last decade this is a 2-3x CPU reduction on the send path. Default is off in most builds because old NICs don’t handle it, but if your hardware is from 2015 or later, turn it on.
• quic_active_connection_id_limit 4;: how many connection IDs the client can have active at once. Higher numbers help with connection migration and NAT rebinding. Default is 2; bumping to 4 or 8 is common.
• http3_stream_buffer_size 64k;: per-stream buffer. Default is small. Bigger means more memory per connection but better throughput on high-bandwidth streams.

If you want to see what’s actually happening, quic_log writes per-packet info to a file. It’s verbose enough that you only want it on for debugging, but for “why is this connection slow” it’s the only way to get ground truth without strace-ing the worker.

The gotchas that will bite you

This is the section I wish I’d had when I started. None of these are bugs in NGINX; they’re all environment issues that NGINX has no way to warn you about.

1. Your firewall is dropping 443/udp

Run ufw status or iptables -L INPUT -n. If you see 443/tcp allowed and nothing about UDP, the kernel is silently dropping every incoming QUIC packet. ufw allow 443/udp, or the iptables equivalent, and re-test. On AWS / GCP / Azure, the security-group rule also defaults to TCP-only, UDP needs an explicit rule. If you have a Cloudflare or Fastly proxy in front, they handle this for you; for everything else, check.

2. The alt-svc header isn’t reaching the client

Every reverse proxy, every CDN, every WAF can strip headers it doesn’t recognise. If you’re behind something old, run curl -sI https://example.com/ | grep -i alt-svc from outside and see what comes back. No header, no HTTP/3. The fix is usually a single line in the proxy config to pass it through, but you have to know to look.

Related: if you set the header without always, NGINX won’t add it to 4xx/5xx responses, and some health-check tools only see 200s from cached error pages and conclude HTTP/3 isn’t enabled.

3. MTU and PMTU discovery

QUIC packets are bigger than the legacy 1280-byte IPv6 minimum because the protocol was designed for modern networks. When a packet exceeds the path MTU, it gets fragmented, and UDP fragments are often dropped by firewalls (because attackers love fragmented UDP). Symptoms: handshake works, then large responses hang or stall. NGINX handles this with QUIC’s built-in PMTU discovery, but if you’ve set net.ipv4.ip_no_pmtu_disc=1 somewhere for “TCP reasons”, that breaks QUIC’s discovery too. Leave PMTU discovery on.

4. Your load balancer is TCP-only

This one’s the killer. If you have an HAProxy, AWS ALB, GCP HTTPS LB, or Nginx Plus in front of your NGINX, check whether it does UDP at all. The classic ALB doesn’t. The new Network Load Balancer does. HAProxy 2.6+ has experimental QUIC support but won’t proxy QUIC to a backend, it terminates it. If your LB doesn’t speak QUIC, you have two choices: terminate QUIC at the LB and proxy plain HTTP/1.1 or H2 to the backend, or bypass the LB entirely for UDP traffic (some people run a separate hostname for QUIC, which is ugly but works).

5. ModSecurity and HTTP/3

If you’ve followed our guide on installing ModSecurity and the OWASP CRS, almost everything works the same over QUIC because ModSecurity sees the request after NGINX has parsed it, the transport is invisible. Two caveats: (a) some older CRS rules look at $server_protocol and assume HTTP/1.1 or HTTP/2 string-matches; HTTP/3 connections show HTTP/3.0, and those rules silently miss-fire. Update to CRS 4.x if you’re still on 3.x. (b) Rate-limiting by source IP gets harder when the client migrates connections across IPs (see “connection migration” up top), the QUIC connection ID is the stable identifier, not the IP, and most WAF rate limiters don’t know about it yet.

While we’re on security: HTTP/3 doesn’t make you immune to BREACH-style compression side-channel attacks. Same compression, same secrets, same problem. Disable HTTP-level compression on responses that mix secrets with attacker-influenced input, the same way you would on HTTP/2.

6. Older Chromium versions and the alt-svc cache

Chrome caches alt-svc records aggressively. If you initially served a broken alt-svc header (wrong port, typo in h3=), Chrome remembers it and keeps trying for the ma duration. You change the server, run curl, see the new header, but your test browser still uses the cached broken one. Visit chrome://net-internals/#alt-svc and clear, or pick a different browser to test fresh. Spent two hours on this once. Never again.

Verifying it actually works

Four tools, in increasing order of paranoia:

curl –http3 (requires a curl built against a QUIC-capable TLS library, Ubuntu 24.04’s curl can do it if you install libcurl4-openssl-dev from a recent source, or just use the curl in our packages):

curl --http3 -sI https://example.com/ | head -1
# Expected: HTTP/3 200

If curl falls back to HTTP/2, it’ll show HTTP/2 200 instead. Check stderr with -v to see why.

Chrome DevTools: open the Network tab, right-click any column header, enable the “Protocol” column. Reload the page. You should see h3 next to your requests. First page-load after a clean cache will be h2 (browser learns alt-svc), and subsequent loads switch to h3. If you never see h3, the alt-svc header isn’t reaching the browser, back to gotcha #2.

h3check.net and http3check.net: third-party probes that hit your domain and tell you what they found. Useful sanity check from outside your own network.

Wireshark / tcpdump on the server: tcpdump -i any -nn 'udp port 443'. If you see no UDP traffic at all when a real client visits, the firewall or NAT is eating your packets before they hit NGINX. If you see UDP packets but NGINX logs no QUIC connections, the listen block isn’t binding the UDP socket, check ss -ulpn | grep :443, the QUIC listener should appear with the NGINX worker PIDs.

When HTTP/3 isn’t worth it

HTTP/3 is wonderful for the open web, where users are on lossy mobile networks loading lots of small assets from a long way away. It is less wonderful for:

• Backend-to-backend traffic on a fast LAN. No packet loss, no head-of-line blocking to fix. The userspace QUIC stack just adds CPU overhead versus plain old TCP+H2.
• Long-lived single-stream connections. Server-sent events, websockets-equivalent persistent streams: QUIC gives you very little here because there’s no multiplexing to benefit from.
• Networks where UDP gets shaped or blocked. Some corporate networks, some hotels, some airline wifi. The browser will silently fall back to TCP, so you’re not broken, but you’ve paid the implementation cost for users who can’t use it.

The good news is that turning it on is additive. Your TCP+H2 listener keeps working for clients that can’t or won’t speak QUIC, and the browsers that can speak it get the benefits transparently. There’s almost no downside to enabling it correctly, the downside is enabling it incorrectly and shipping a half-broken alt-svc header that makes browsers waste time trying QUIC against a dead UDP socket.

FAQ

Related reading

• Zstd vs Brotli vs zlib-ng: The NGINX Compression Deep Dive: compression matters more than transport for total page weight; pair HTTP/3 with proper static precompression.
• How to Install ModSecurity and OWASP CRS on NGINX: your WAF still works over QUIC, but check the rule notes above.
• What Is the BREACH Attack? How It Works and How to Stop It: HTTP/3 doesn’t fix compression side-channels.
• NGINX Modules optimized & extended: the full set of dynamic modules in our HTTP/3-capable nginx packages.

So we rebuilt it. The myguard hardened OpenSSH 10.3 packages for Debian and Ubuntu give you post-quantum hybrid key exchange by default, AEAD-only ciphers, a loaded AppArmor profile, a fail2ban jail that just works, a systemd unit that actually drops capabilities, a monthly moduli refresh timer, compiler flags well past Debian’s own hardening=+all (a discipline we apply elsewhere too, see our Docker hardening guide and the HTTP/3 and QUIC on NGINX setup), and, the bit we’re most pleased with, three real, apt-installable server packages that let you pick the attack surface you actually need without recompiling anything.

What follows is the full tour: what we ship, why every choice was made, the apt commands, a 2026 SSH key recipe (Ed25519, security keys, certificates), and a long tail of operational tips that the Debian default should have absorbed a decade ago.

Why a hardened OpenSSH? Why rebuild it at all?

Let’s be fair to the Debian maintainers for a sentence: OpenSSH itself, the thing the OpenBSD team writes, is one of the best pieces of security software ever shipped. The problem isn’t OpenSSH. The problem is what happens to it on the way to your apt mirror.

The shipped configuration is built for an imaginary lowest-common-denominator user, a workstation that runs X11, a laptop that might suddenly need to talk to a Solaris box from 2003, an AD-joined desktop that wants Kerberos session tickets. Every default reflects that user. None of them is you.

The roll call from a stock apt install openssh-server:

• X11Forwarding yes: handy on a desktop, free tunneling for an attacker on a server.
• KbdInteractiveAuthentication defaults that interact badly with PAM and become a brute-force vector the moment someone re-enables password auth “just for a minute”.
• Algorithm lists that include ssh-rsa, NIST-P ECDH, diffie-hellman-group14-sha1, and the whole CBC family, because the maintainer can’t be sure you don’t have a 2010 router on your network.
• One /etc/ssh/moduli file, byte-identical on every install on Earth, never regenerated.
• An AppArmor profile sitting unused in another package.
• A ssh.service with effectively no ProtectSystem, no RestrictAddressFamilies, no SystemCallFilter, no CapabilityBoundingSet: because someone in #debian-mentors thinks sandboxing is too opinionated.
• Kerberos linked into the one sshd binary you get, even though three-quarters of Linux servers will never see a KDC.

None of this is a bug. It’s the price of being a general-purpose distribution. The cost is that every serious shop ends up writing the same Ansible role to undo it, every audit firm bills the same hours to re-discover it, and the actual exposed surface of SSH on the open internet stays exactly as wide as it was in 2014. We figured that was enough.

Pick the attack surface you actually need

Debian gives you one openssh-server binary, built with everything: PAM, SELinux, audit, libedit, security keys, wtmpdb, Kerberos. You get all of it whether you wanted it or not, you get libwrap for free even though TCP wrappers haven’t been a good idea since the Bush administration, and the binary on a hardened bastion in a co-lo is bit-for-bit identical to the one on a developer’s laptop. We split it into three.

All three install /usr/sbin/sshd and Conflicts: each other, so apt swaps them transactionally. A host that starts as openssh-server and a year later gets folded into AD becomes:

sudo apt install openssh-server-gssapi

and apt removes the old binary, installs the new one, and the unit restarts. No Ansible task, no role variable, no rebuild.

The hardening drop-in, the systemd lock-down, the AppArmor profile, the fail2ban jail and the moduli refresh timer all live in a fourth package, openssh-server-common, that every flavour Depends: on. Whichever sshd you install, the same hardened defaults apply. You can’t accidentally have the gssapi flavour without the systemd sandbox; the dependency graph won’t let you.

What openssh-server-common ships

1. A hardened sshd_config drop-in that’s actually removable

We install /etc/ssh/sshd_config.d/00-myguard-hardening.conf. Because OpenSSH applies the first occurrence of any keyword and the shipped sshd_config pulls in sshd_config.d/*.conf before its own body takes effect, this drop-in wins on every conflict. The point isn’t just to be authoritative, it’s that any admin who needs to relax one knob writes a 99-something.conf next to it. No editing the main file. No conffile-rejected-on-upgrade dialog at four in the morning. The hardening is a file, not a patch.

What’s in it:

• Post-quantum hybrid KEX first: mlkem768x25519-sha256 then sntrup761x25519-sha512, then curve25519-sha256. NIST-P ECDH and SHA-1 DH groups are gone. If “harvest now, decrypt later” is a thing, this is the one config line that matters most.
• AEAD ciphers only: chacha20-poly1305, aes256-gcm, aes128-gcm. CBC, 3DES, arcfour and plain CTR are out: they’ve been bad ideas for various lengths of time between five and twenty years.
• ETM MACs only: hmac-sha2-512-etm, hmac-sha2-256-etm, umac-128-etm. The non-ETM variants leak a length oracle; we don’t care if your 2013 client doesn’t like that.
• Signatures: Ed25519, ECDSA P-256/384/521, RSA-SHA2. ssh-rsa (which is RSA with SHA-1) is removed from HostKeyAlgorithms, PubkeyAcceptedAlgorithms and CASignatureAlgorithms. It’s 2026.
• Auth: password off, root prohibit-password, empty passwords off, keyboard-interactive off, host-based off, rhosts ignored, known-hosts ignored.
• Forwarding: X11 off, TCP off, agent off, tunnel off, user-environment off. If you need any of these on, you’ll know what you’re doing and which override to write.
• Brute-force economics: LoginGraceTime 30s, MaxAuthTries 3, MaxStartups 10:30:60, ClientAliveInterval 300, ClientAliveCountMax 2.
• PerSourcePenalties (OpenSSH ≥ 9.8): the killer feature nobody talks about. sshd tarpits abusive sources by /24 (IPv4) or /48 (IPv6) source block, ramping from 5 seconds on an auth failure to a 1-hour cap. fail2ban still helps if you want fancy correlation, but for the simple “China is scanning port 22 again” case, you don’t even need it.
• LogLevel VERBOSE: every successful login emits the key fingerprint that authenticated it. Your SIEM will thank you the first time you have to investigate a key compromise.

2. A systemd unit that actually sandboxes

The stock ssh.service on Debian is, charitably, conservative. It runs sshd. It restarts on failure. That’s the security boundary. We drop /usr/lib/systemd/system/ssh.service.d/hardening.conf on top of it, and the systemd merge gives you:

• ProtectSystem=strict with ProtectHome=read-only and an explicit, minimal ReadWritePaths=. sshd can write to /var/log, /run/sshd, /var/lib/sss and a few other places that matter. It cannot write anywhere else. If your sshd ever decides to drop a binary in /tmp and run it, that’s a kernel-enforced “no” rather than a hope.
• CapabilityBoundingSet= whitelisted. sshd ships with a long list of effective capabilities it doesn’t need; we drop the boundary to the dozen that PAM and the privsep child actually use.
• MemoryDenyWriteExecute=yes, LockPersonality=yes, RestrictRealtime=yes. The first one is the load-bearing knob in 2026: an exploit that smuggles in shellcode now has to defeat W^X in the address space, not just bypass NX.
• RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK. No AF_PACKET, no AF_BLUETOOTH, no AF_XDP. sshd is a TCP daemon: it doesn’t need to learn new tricks.
• SystemCallFilter=@system-service @resources minus @privileged @debug @mount @reboot @swap @cpu-emulation @obsolete. The kernel rejects most of the syscalls a post-exploitation toolkit reaches for, before sshd’s process ever sees them.
• Plus the alphabet soup: RestrictNamespaces, ProtectKernelTunables, ProtectKernelModules, ProtectKernelLogs, ProtectClock, ProtectHostname, ProtectProc=invisible, ProcSubset=pid.

One knob we don’t set: NoNewPrivileges=yes. pam_unix and pam_systemd rely on suid helpers, and turning NNP on at the unit level breaks login on a stock distribution. If you’ve gone openssh-server-minimal and have no PAM stack to worry about, you can add it back in a 99-*.conf override, that’s exactly the situation it was designed for.

3. An AppArmor profile that’s actually installed

Debian’s apparmor-profiles package ships an sshd profile that doesn’t get loaded. It sits there. It has sat there for years. Our package drops one in /etc/apparmor.d/usr.sbin.sshd, and the postinst calls apparmor_parser -r automatically if AppArmor is active on the host. You install the package, the profile is live. Imagine that.

It ships in complain mode, deliberately. Anyone who’s done this before will tell you: AppArmor plus sshd is a tar pit. Every PAM module, every NSS backend (sssd, ldap, winbind), every login shell that might exist on the system needs an explicit allow rule. A profile that’s even slightly too tight will silently lock you out of your own machine at the worst possible moment, which on a server reachable only by SSH is also the only possible moment.

Complain mode logs would-be denials to dmesg and /var/log/audit/audit.log without blocking. Tail them for a few weeks, fix the genuine misses, then promote:

sudo aa-enforce /usr/sbin/sshd

4. A fail2ban jail snippet

We drop /etc/fail2ban/jail.d/myguard-sshd.conf. Backend is systemd-journal, no scraping /var/log/auth.log, no log-rotation games. maxretry=3, findtime=10m, bantime=1h, and bantime-incrementing on repeat offenders up to 30 days. If fail2ban isn’t installed, the file is inert. openssh-server Recommends: fail2ban, so a default apt install pulls it in. If you’ve globally disabled Recommends in your apt config, that’s on you.

5. Monthly moduli regeneration

The /etc/ssh/moduli file Debian ships is byte-identical on every install. It was generated once, a long time ago, by someone whose name you can find in git log. We install a ssh-moduli-refresh.timer that runs monthly with a 24-hour randomised delay, regenerates fresh DH moduli at 2048/3072/4096/6144/7680/8192 bits, and atomically swaps them in. The service is heavily sandboxed (idle CPU class, NoNewPrivileges, blank RestrictAddressFamilies=) because ssh-keygen -M generate is CPU-bound for tens of minutes on a small VPS and we’d rather it didn’t have the run of the place while it grinds.

Yes, you could schedule this yourself with a cron job. You haven’t, though.

6. Compiler flags past hardening=+all

Debian’s hardening=+all gets you PIE, RELRO, stack-protector-strong, FORTIFY=2. That’s a baseline. Our build appends:

• -D_FORTIFY_SOURCE=3: Debian’s default is still 2; FORTIFY=3 catches a strict superset.
• -fstack-clash-protection: defuses stack-clash exploits at compile time.
• -fcf-protection=full on amd64: Intel CET / shadow stacks. Free CFI on any post-2020 silicon.
• -mbranch-protection=standard on arm64: PAC + BTI. Same idea, different ISA.
• -Wl,-z,now -Wl,-z,relro: full RELRO, no lazy binding. .got.plt isn’t writable at runtime.
• -O3 -flto=auto -fno-plt -fno-semantic-interposition -ffunction-sections -fdata-sections -Wl,--gc-sections: speed and dead-code elimination on top of the security. Same binary that protects you better also runs faster.

None of these flags is exotic. They’ve all been stable for years. They just haven’t trickled down into Debian’s hardening=+all default, which is a process problem rather than a technical one.

7. Reproducible builds

Our debian/rules pins SOURCE_DATE_EPOCH from the changelog timestamp when it isn’t already set. Two builds of the same source produce byte-identical binaries. If a malicious build server ever ships you a tampered sshd, you can prove it.

8. Autopkgtests that fail the build

Three tests run on every build, and if any of them fails the package doesn’t ship:

• sshd-hardened-defaults: runs sshd -T on the just-built binary, asserts every hardened knob is in effect, fails the build if a deprecated cipher, KEX or MAC ever sneaks back into the active config.
• sshd-flavours-exist: all three flavour packages each ship a working /usr/sbin/sshd.
• apparmor-profile-loads: the profile parses with no warnings and loads cleanly when AppArmor is active.

Translation: the hardening can’t quietly regress between releases. The build itself enforces it.

Installing it

If you don’t have the myguard repo configured yet, follow the quick repo setup first. Then pick your flavour:

# The default. Use this everywhere except the two edge cases below.
sudo apt install openssh-server

# Active Directory or MIT Kerberos shop.
sudo apt install openssh-server-gssapi

# Bastion jumphost, container, recovery image.
sudo apt install openssh-server-minimal

Whichever you choose, apt pulls in openssh-server-common and lays down the hardened drop-in, the systemd override, the AppArmor profile, the fail2ban jail and the moduli timer. Restart sshd once:

sudo systemctl daemon-reload
sudo systemctl restart ssh

Confirm the live config is the live config:

sudo sshd -T -C user=root | grep -E '^(kex|cipher|mac|passwordauth|x11|permittun)'

If you want to switch flavours later, say, the host gets folded into AD, it’s one command:

sudo apt install openssh-server-gssapi

The Conflicts: relationship handles the removal. The systemd unit handles the restart. openssh-server-common doesn’t move, so none of your hardening churns.

The 2026 SSH key recipe

If you do nothing else after reading this: stop generating RSA keys. Ed25519 is smaller, faster, has no parameter-generation footguns, isn’t subject to the SHA-1 deprecation churn, and has been the right answer since 2014. If your ~/.ssh/id_rsa is older than your kids, today is a good day.

The one-liner

ssh-keygen -t ed25519 -a 100 -C "$(whoami)@$(hostname)-$(date +%Y%m%d)"

• -t ed25519: modern Edwards-curve signature. 32-byte public key, 64-byte signature, no nonce-reuse class of bug. Boring, which is what you want.
• -a 100: 100 rounds of the bcrypt-pbkdf KDF on the encrypted private key. An attacker who walks off with your ~/.ssh/id_ed25519 still has to crack that passphrase, and 100 rounds slows brute-force by orders of magnitude. You pay it once, when ssh-agent unlocks the key.
• -C "...": a comment that says which laptop generated it and when. Future you, finding three half-remembered keys in some old authorized_keys file in 2029, will be grateful.

Pick a real passphrase. “I want unattended logins”, that’s what ssh-agent is for. Unlock the key once, stay unlocked for the session, no typing.

Push it to a server

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server.example.com

With our package, password auth is already off, so the first key has to get there some other way: the cloud provider console, your configuration management, an existing key on a peer host. Once it’s in:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

sshd refuses to read group-writable or world-readable key files, by design. That refusal is one of the few things on a hardened sshd that bites people. Now you know.

Hardware keys, if you have one

OpenSSH speaks FIDO2 / WebAuthn natively via sk-ssh-ed25519. YubiKey, NitroKey, OnlyKey, anything with the U2F/FIDO2 spec works:

ssh-keygen -t ed25519-sk -O resident -O verify-required \
    -C "yubikey-$(date +%Y%m%d)"

• ed25519-sk: the security-key variant. The private scalar never leaves the token; there is no software-only copy to steal.
• -O resident: the key handle is stored on the token itself. Pull it back onto a fresh laptop with ssh-keygen -K.
• -O verify-required: every authentication needs a PIN and a touch. Don’t skip this one. An attacker with physical access to the token can otherwise log in by tapping it, which is roughly the opposite of what you bought a hardware key for.

openssh-server and openssh-server-gssapi build with --with-security-key-builtin, so sk-* works out of the box without runtime libfido2. openssh-server-minimal doesn’t, by design, since minimal is for bastion hosts and containers where the FIDO key lives on the client and the server never needs to know.

If you really must use RSA

Sometimes a legacy system insists. Generate at least 4096 bits, and remember that the signature algorithm matters more than the key type, our drop-in already drops ssh-rsa (RSA with SHA-1) and only accepts rsa-sha2-256 / rsa-sha2-512 from the same RSA key:

ssh-keygen -t rsa -b 4096 -a 100 -C "rsa-$(date +%Y%m%d)"

If a server ever rejects your RSA key with “no mutual signature algorithm”, that’s the diagnosis: your client wants ssh-rsa, the server demands SHA-2. Fix it on the client:

# ~/.ssh/config
Host stubborn-old-thing.example.com
    PubkeyAcceptedAlgorithms +rsa-sha2-512,rsa-sha2-256

Tips, tricks, and things the Debian default should already do

Use SSH certificates, not authorized_keys

Past a handful of users or hosts, copying public keys around becomes an audit nightmare. SSH certificates fix it: a CA signs short-lived user certificates (“alice can log in as root on hosts matching *.prod.example.com for the next 8 hours”), and the server only knows the CA’s public key via TrustedUserCAKeys. Rotation, revocation, audit, all become trivial. Our hardening drop-in already restricts CASignatureAlgorithms to the modern set.

Minimal CA bring-up:

# on a hardened host (offline-ish, or in a vault)
ssh-keygen -t ed25519 -f ca_user_key -C "user-ca-$(date +%Y%m%d)"

# on every server, in /etc/ssh/sshd_config.d/20-userca.conf
TrustedUserCAKeys /etc/ssh/ca_user_key.pub

# issue an 8-hour certificate for alice
ssh-keygen -s ca_user_key -I alice@laptop -n alice,deploy \
    -V +8h -z 1 ~/.ssh/id_ed25519.pub

The result is a ~/.ssh/id_ed25519-cert.pub alongside the user key. ssh presents it automatically. When Bob leaves the team, you don’t grep two hundred authorized_keys files, you add his cert serial to a RevokedKeys file and push that one file out.

Allowlist sources with Match

Most servers don’t need to accept SSH from the entire internet. In /etc/ssh/sshd_config.d/10-source-allowlist.conf:

Match Address !10.0.0.0/8,!192.168.0.0/16,!2001:db8::/32,*
    DenyUsers *

The traditional answer was /etc/hosts.allow with TCP wrappers. We dropped --with-tcp-wrappers on purpose: libwrap has been deprecated for over a decade, upstream OpenSSH removed it in 6.7, and Debian only kept it because backwards compatibility is a religion. Match blocks and nftables do the same job, better.

Put SSH into your monitoring

The LogLevel VERBOSE in our drop-in exists for one reason: every successful login records the key fingerprint that authenticated it. That single line is the difference between knowing who got in and guessing. Pipe it to your SIEM:

journalctl -u ssh -f --output=json \
    | jq 'select(.MESSAGE | test("Accepted publickey"))'

Or a quick one-shot review of this week’s logins:

journalctl -u ssh --since "1 week ago" \
    | grep "Accepted publickey" \
    | awk '{print $9, $11, $13}' | sort | uniq -c | sort -rn

Don’t move SSH to port 2222

It’s the oldest folklore recommendation in the book and it hides exactly nothing from a Shodan-scale scan. What actually quietens your logs is per-source rate limiting (which we ship) and fail2ban (which we ship). Keep SSH on 22 and avoid the firewall rule, the monitoring exception, the runbook footnote, and the inevitable “wait, why can’t I ssh to that host” thread on Slack.

If you must allow passwords, scope them

A legacy vendor really needs password auth. Fine. Confine it to the VPN:

Match Address 10.99.0.0/24
    PasswordAuthentication yes
    KbdInteractiveAuthentication yes

ProxyJump, not nested ssh

# ~/.ssh/config
Host bastion
    HostName bastion.prod.example.com
    User ops

Host prod-*
    ProxyJump bastion
    User deploy

ssh prod-web-04 now does the right thing, single TCP tunnel through the bastion, bastion never holds your private key, no agent forwarding required, no “ssh-in-ssh-in-ssh” muscle memory. Pairs naturally with openssh-server-minimal on the bastion: nothing but sshd and authorized_keys, the way bastions were meant to be.

Multiplex sessions

# ~/.ssh/config
Host *
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m

The second ssh to a host within 10 minutes reuses the first one’s TCP connection and skips the entire handshake. Ansible runs faster. scp in a loop runs faster. Rapid-fire one-liners run faster. Free.

Verify host keys the first time

“The authenticity of host can’t be established, are you sure?” is a security checkpoint, not a nuisance. Get the real fingerprints on the server:

for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$f"; done

Compare the Ed25519 line to what your client prints. Better: publish them in DNS as SSHFP records and set VerifyHostKeyDNS yes in your client. Our package builds with DNSSEC SSHFP support, Debian’s dnssec-sshfp.patch is in our applied series.

Tune PerSourcePenalties for your traffic shape

Our defaults assume sshd faces the open internet. If yours sits behind a load balancer or a VPN that aggregates many real clients to one source IP, raise the limits or you’ll tarpit legitimate users:

# /etc/ssh/sshd_config.d/50-behind-lb.conf
PerSourceMaxStartups 32
PerSourceNetBlockSize 32:128

Hash your known_hosts

If your laptop gets compromised, an attacker reads ~/.ssh/known_hosts and learns every server you’ve ever connected to. They get a free reconnaissance map. Hash it:

echo 'HashKnownHosts yes' >> ~/.ssh/config
ssh-keygen -H              # rewrites the existing file with hashed entries

Restrict keys with options

Per-key restrictions in authorized_keys tighten things down even further than the global config:

# backup user — only from the NAS, only running restic-server, nothing else
restrict,from="10.0.0.42",command="/usr/local/bin/restic-server" ssh-ed25519 AAAAC3Nz... backup@nas

restrict turns off agent forwarding, port forwarding, pty, X11 and user-rc; opt back in explicitly only what you need. from= pins the source IP. command= forces a specific command no matter what the client asks for. Combine all three and an attacker who steals the private key still can’t do anything but run restic-server from the NAS’s IP. That’s the goal.

When things break

“My ancient client can’t connect”

An OpenSSH from 2014 won’t negotiate our algorithm list. Three options, ranked:

1. Update the client. Almost always the right answer.
2. Add a Match Address block that relaxes the algorithm set just for that source.
3. Shadow our drop-in with a 99-*.conf that adds whatever the client needs. Leave a comment that says why.

“AppArmor is blocking something”

The profile ships in complain mode, so this shouldn’t happen unless you flipped it to enforce. Check dmesg for apparmor="DENIED", run aa-logprof to generate the missing rules, and drop them in /etc/apparmor.d/local/usr.sbin.sshd rather than editing the shipped profile. Or open an issue against the package, if your stack hits the denial, others’ will too.

“sshd won’t start after upgrade”

sudo sshd -t validates the config. journalctl -u ssh -n 50 --no-pager shows the actual error. The usual cause is a leftover file in /etc/ssh/sshd_config.d/ from a previous install that references a removed keyword. Our drop-in is 00-myguard-hardening.conf; anything with a higher number wins on conflicting keys.

“I installed openssh-server-minimal and pam_systemd broke”

Working as designed: minimal has no PAM. pam_systemd session registration, pam_limits, motd, Kerberos PAM modules, none of it exists in that binary. If you need any of those, you wanted openssh-server. Minimal is for containers, bastions and recovery images, where having no PAM is the feature.

Why not just roll your own?

You absolutely can. Everything above is a few hours of work for any competent sysadmin, plus the ongoing cost of keeping it current as OpenSSH ships new algorithms, deprecates old ones, and adds knobs like PerSourcePenalties. We did the work, we keep doing it, and we ship the result as a single apt install. The autopkgtests in our build pipeline make sure the defaults don’t quietly regress between releases.

The packages are out now for Debian bookworm and trixie, Ubuntu noble and resolute. Pull them from our repository. Pick the flavour that matches your use case. File issues if you find any. Hardened SSH should have been the default a long time ago, until it is, you can have ours. Background reading: the upstream OpenSSH release notes, the AppArmor project, and NIST’s post-quantum cryptography programme for the ML-KEM context.

Here’s the truth nobody puts on the official Docker page: a default Docker container is barely a container at all. It’s a process running as root, with most Linux capabilities, on a writable filesystem, sharing a kernel with everything else on your box. If something inside the container goes wrong, a vulnerable nginx, a php-fpm worker that got popped, a forgotten debug endpoint, the blast radius is wider than you think.

The good news: a hardened container is genuinely close to bulletproof. The bad news: you have to opt in to every single layer of hardening. This guide is the checklist I wish someone had handed me when I started self-hosting WordPress, Vaultwarden, Roundcube, and the other ten things that live on my home server.

No jargon without an explanation. Pretend you’ve never written a Dockerfile in your life. By the end you’ll have a hardened compose file for NGINX/Angie and PHP-FPM, and you’ll understand why every flag is there.

Why default Docker is not actually safe (and what Docker hardening means)

If you run docker run -d nginx right now, you get all of the following, whether you wanted them or not:

• The container’s PID 1 runs as root. If anything inside the container is exploited and the attacker gets a shell, that shell is root inside the container.
• The dockerd daemon itself runs as root on the host. A container escape (and there have been several historic ones: CVE-2019-5736 was the famous runc escape) lands the attacker straight at host-root.
• The container has most Linux capabilities: CAP_NET_RAW, CAP_NET_BIND_SERVICE, CAP_CHOWN, CAP_SETUID, CAP_SETGID, CAP_KILL, CAP_AUDIT_WRITE and others. Far more than nginx actually needs.
• The container filesystem is writable. An attacker can drop a webshell wherever the running user can write, and it sticks around for the life of the container.
• Process privilege escalation is allowed. Without no-new-privileges, a setuid binary inside the container can elevate.
• The kernel is shared. A kernel exploit (you’ll see “container escape via dirty-pipe” or similar in the headlines every couple of years) hits everyone on the box.

None of this is a Docker bug. It’s a deliberate choice to default to “convenient” over “secure.” The hardening flags exist; you just have to use them. Let’s walk through them, in order of how much they help.

Layer 1: don’t run the daemon as root (rootless mode)

The single biggest hardening win is moving the Docker daemon out of root. Two ways to do it:

• Docker rootless mode: ships with Docker 20.10+. Run dockerd-rootless-setuptool.sh install as your normal user, and from then on docker commands talk to your personal daemon, owned by your user. A container escape now lands at your user, not at root.
• Podman: designed rootless from day one, no daemon at all (each podman run spawns a normal user process). Drop-in compatible with most docker run and Compose files.

I run a mix on my own machine: Podman for one-shot containers, Docker rootless for the long-running compose stacks. Both deliver the same security win: the privileged Docker daemon is gone.

Trade-offs to know:

• Rootless containers can’t bind to ports below 1024 by default. Solution: put a single privileged reverse proxy in front (or use net.ipv4.ip_unprivileged_port_start=80 as a sysctl).
• Some volume-mount and overlay-network features need extra setup (slirp4netns, fuse-overlayfs).
• docker run --privileged is mostly meaningless rootless: which is exactly what you want.

If you take one thing from this whole post, take this: run Docker rootless or use Podman. The other layers are nice; this one is foundational.

Layer 2: make the container filesystem read-only

Most well-behaved server processes never need to write to their own filesystem. nginx serves static files. PHP-FPM reads scripts and writes to a session store and a log. Vaultwarden writes to a single SQLite file. If you flip the container filesystem to read-only and then mount just the paths that need writes, an attacker who drops a webshell into /usr/local/bin/ finds out that file system is read-only the hard way.

In Compose:

services:
  web:
    image: nginx:1.27-alpine
    read_only: true
    tmpfs:
      - /tmp
      - /var/cache/nginx
      - /var/run
    volumes:
      - ./site:/usr/share/nginx/html:ro

The tmpfs mounts give the container a few writable scratch directories backed by RAM, they vanish on restart. Anything else the process tries to write fails with EROFS. nginx, php-fpm, postgres, redis, vaultwarden, postfix, dovecot, all of them will run happily in this mode once you’ve identified the directories they legitimately need writable.

How to find out? Run the container, hit it with normal traffic, then docker exec -it <name> sh -c 'mount | grep -v ro'. Anything writable that isn’t a tmpfs or bind-mount is a candidate for “either move to tmpfs or live without.”

Layer 3: drop every capability, add back only what you need

Linux capabilities are the modern way to slice up what used to be “all of root or none of it.” A normal process running as root has 40+ capabilities. A normal container gets a curated default subset, but it’s still wildly over-privileged for what most apps actually do.

The right approach: drop all of them, then add back only the specific ones the app needs. For nginx in a container that listens on port 80:

services:
  web:
    image: nginx:1.27-alpine
    cap_drop: [ALL]
    cap_add: [NET_BIND_SERVICE]

That’s it. NET_BIND_SERVICE is the only capability nginx needs to bind to port 80. With that single allow, an attacker who escapes the nginx process has the privileges of “a process that can bind to a low port.” That’s it. No chown, no setuid, no net_raw, no kill, nothing.

For PHP-FPM that listens on a Unix socket or a TCP port above 1024:

services:
  php:
    image: php:8.4-fpm-alpine
    cap_drop: [ALL]
    # NO cap_add at all — PHP-FPM doesn't need a single capability

That feels wrong the first time you see it. It’s correct. Read the capabilities(7) man page if you’re unsure, nothing PHP-FPM does at runtime requires any capability.

Layer 4: no-new-privileges

This one is a single line and a huge win. It tells the kernel: “no process inside this container can ever gain more privileges than it started with.” Setuid binaries are neutered. su stops working. sudo stops working. pkexec stops working.

services:
  web:
    image: nginx:1.27-alpine
    security_opt:
      - no-new-privileges:true

Combine this with running as a non-root user inside the container (most well-built images do this already) and you’ve removed an entire family of attack chains. The 2019 runc escape (CVE-2019-5736) and several since have depended on tricking the kernel into running a binary with elevated privileges; no-new-privileges blocks that class outright.

There is no good reason ever to leave this off for a normal application container.

Layer 5: don’t run as root inside the container

Even with the host-level Docker daemon rootless, an application running as UID 0 inside the container is needlessly powerful. Run as a normal user.

Most well-built modern images already do this. The official nginx:alpine image runs as the nginx user (UID 101). The official php:8.4-fpm-alpine image runs FPM workers as www-data (UID 82). If you’re writing your own Dockerfile, you should always include:

RUN adduser -D -u 33 appuser
USER appuser

And in Compose, you can override the runtime user explicitly:

services:
  php:
    image: deb.myguard.nl/php-fpm:8.4
    user: "33:33"   # www-data

For an extra layer, enable Docker’s user-namespace remapping (userns-remap in /etc/docker/daemon.json). Even if the process inside the container thinks it’s UID 0, the kernel sees it as an unprivileged UID on the host (e.g. UID 100000). This breaks a class of file-permission attacks across the container/host boundary.

Layer 6: pick a base image that isn’t a Swiss army knife

“Use Alpine for security” is one of those folk-wisdom statements that’s half right. Smaller images do have fewer CVEs by sheer surface-area, but the modern landscape has three serious contenders:

The honest answer: match the base to the app. WordPress + PHP-FPM with our myguard packages? debian:trixie-slim, every time, we test against it, the packages install cleanly, the apt sources just work. A Go static binary you wrote yourself? Distroless. A small Node.js script? Alpine.

What matters more than the base image, every single time: rebuild and patch on a schedule. The freshest distroless image with a six-month-old base layer is less secure than yesterday’s debian-slim with apt-updated packages.

Layer 7: secrets don’t belong in your image

The most common own-goal in container security: baking a DATABASE_PASSWORD=hunter2 into a Dockerfile ENV, or worse, into a COPY .env /app/. That credential is now in every layer of every published image, forever. docker history will show it. Anyone who pulls the image can extract it with docker save.

Three good ways to ship secrets to a container, ranked by my preference for self-hosters:

1. Bind-mount a file the container reads at startup. Keep the file outside git, lock it down to mode 600.
   volumes: [./secrets/db.env:/run/secrets/db.env:ro]
2. Docker secrets / Swarm secrets: works fine standalone with docker compose --profile production. Secrets land as files under /run/secrets/ inside the container.
3. External secret store (Bitwarden CLI, age-encrypted files, HashiCorp Vault). Overkill for most homelabs but worth knowing about.

What never to do: ENV DATABASE_PASSWORD=... in the Dockerfile, or --env DATABASE_PASSWORD=... on the command line (it leaks to ps on the host).

Layer 8: network segmentation by default

Every container Docker creates joins the default bridge network and can talk to every other container on that network. That’s the opposite of what you want.

The right pattern: each compose stack gets its own network. The reverse-proxy container joins both the public-facing network and the stack’s internal network. The application containers (PHP-FPM, database, cache) join only the internal network. Now an attacker who pops PHP-FPM can’t ping a neighbouring stack’s postgres.

services:
  web:
    image: nginx:1.27-alpine
    networks: [public, internal]
    ports: ["80:80"]
  php:
    image: deb.myguard.nl/php-fpm:8.4
    networks: [internal]   # NO public exposure
  db:
    image: postgres:17-alpine
    networks: [internal]

networks:
  public:
    driver: bridge
  internal:
    driver: bridge
    internal: true   # blocks egress to the internet too

The internal: true on the database network is the cherry on top: a database container on an internal-only network cannot exfiltrate data to the public internet even if it’s owned. Most data-stealer malware fails silently against this.

Layer 9: scan your images, every build

Static analysis of container images takes thirty seconds and catches an embarrassing number of issues. The three tools I actually use:

• Trivy (github.com/aquasecurity/trivy): one binary, scans an image for CVEs in OS packages and language deps. trivy image nginx:1.27-alpine prints a table you can act on in minutes.
• Grype (github.com/anchore/grype): similar idea, different vuln database. I run both because they don’t always agree.
• Syft (github.com/anchore/syft): generates a software bill of materials (SBOM) in SPDX/CycloneDX format. Useful when a new CVE drops and you need to know which of your images are affected without re-scanning.

Wire any of these into your CI and reject builds with critical CVEs. For self-hosters without a CI, even a manual trivy image $(docker images -q | head) on a Sunday afternoon catches the worst stuff.

Layer 10: logging that survives the container

When (not if) something goes wrong inside a container, you want logs you can read. Two rules:

• Log to stdout/stderr, not to a file inside the container. The Docker logging driver captures stdout and ships it where you want.
• Pick a real logging driver: json-file with rotation, journald, or push to Loki / Vector. The default unbounded json-file driver will fill your disk eventually.

In /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5"
  }
}

Per-container override in Compose:

services:
  web:
    logging:
      driver: journald
      options:
        tag: "{{.Name}}"

Forensics are only possible if the evidence still exists when you go looking.

Putting it all together: a hardened nginx + PHP-FPM stack

Here’s a complete, real-world docker-compose.yml for a hardened WordPress / PHP stack using our myguard packages. Every flag is one of the ten layers above; no flag is decorative.

services:
  web:
    image: deb.myguard.nl/angie:1.11.5-alpine
    read_only: true
    cap_drop: [ALL]
    cap_add: [NET_BIND_SERVICE]
    security_opt:
      - no-new-privileges:true
    user: "101:101"   # nginx
    tmpfs:
      - /tmp
      - /var/cache/angie
      - /var/run
    ports: ["80:80", "443:443"]
    networks: [public, internal]
    volumes:
      - ./conf/angie.conf:/etc/angie/angie.conf:ro
      - certs:/etc/letsencrypt:ro
      - wp-content:/var/www/html/wp-content:ro
    logging:
      driver: journald

  php:
    image: deb.myguard.nl/php-fpm:8.4-snuf
    read_only: true
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    user: "33:33"   # www-data
    tmpfs:
      - /tmp
      - /var/run
    networks: [internal]   # no public exposure
    volumes:
      - ./conf/wordpress-strict.rules:/etc/php/8.4/php-snuffleupagus/active.rules:ro
      - ./conf/www.conf:/etc/php/8.4/fpm/pool.d/www.conf:ro
      - wp-content:/var/www/html/wp-content
    logging:
      driver: journald

  db:
    image: mariadb:11-noble
    read_only: false   # mariadb really does need to write
    cap_drop: [ALL]
    cap_add: [CHOWN, SETUID, SETGID]
    security_opt:
      - no-new-privileges:true
    networks: [internal]
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
    secrets: [db_root_password]
    volumes:
      - db-data:/var/lib/mysql
    logging:
      driver: journald

networks:
  public:
    driver: bridge
  internal:
    driver: bridge
    internal: true

volumes:
  certs:
  wp-content:
  db-data:

secrets:
  db_root_password:
    file: ./secrets/db_root_password

The PHP container in this stack also loads Snuffleupagus via the rules file mount, so even if the attacker bypasses all ten Docker layers and gets PHP execution, Snuffleupagus blocks the function calls they’d need to actually do damage. Defence in depth, in three independent layers.

The 60-second Docker hardening checklist

If you remember nothing else from this post, run through this list on every container you deploy:

1. Daemon running rootless? (or Podman)
2. read_only: true + tmpfs for the writable bits?
3. cap_drop: [ALL] with only the specific caps added back?
4. security_opt: [no-new-privileges:true]?
5. user: set to a non-root UID?
6. Base image fresh, scanned with Trivy or Grype?
7. Secrets via files, not ENV?
8. App container on an internal: true network?
9. Logging driver with rotation set?
10. Restart policy chosen deliberately (unless-stopped for services, not always)?

Ten flags. Five minutes per stack. A real attacker has to find a real kernel CVE to escape this. Worth the effort.

Frequently asked questions

Related posts

• PHP Snuffleupagus tutorial: the PHP-interpreter-layer hardening that pairs perfectly with this container-layer hardening.
• How to install ModSecurity and OWASP CRS on NGINX: the HTTP-layer WAF that sits in front.
• Self-hosted Vaultwarden: a real-world hardened compose example end-to-end.
• docker-cms: hardened PHP 8.5 image for WordPress: our pre-hardened image so you don’t have to start from scratch.
• Angie and NGINX Docker images: daily-rebuilt, full-modules, ready to drop into a hardened compose.

See also: Hardened OpenSSH 10.3 for Debian and Ubuntu for the SSH side of host hardening, and the Docker packages overview.

First things first, what even is rspamd?

Imagine you run a hotel. Every day, three thousand strangers show up at the front desk demanding a room. Some are lovely guests with reservations. Some are conmen with fake passports. Some are wearing trench coats and clearly trying to sell you knock-off Rolexes. You need a bouncer. A very, very smart bouncer who can read body language, sniff out fake IDs, remember faces, and ban the same scammer who tried it last Tuesday.

That is rspamd. It is a fast, open-source spam filter, written in C and Lua, that sits in front of your mail server (usually Postfix paired with Dovecot) and judges every single email that tries to walk through your door. It scores each one, decides if it is a guest or a grifter, and acts accordingly: deliver, tag, quarantine, or slam the door shut. And unlike its older, slower cousin SpamAssassin (we love you, Spammy, but it is 2026), rspamd does this in milliseconds, in parallel, with a gorgeous web interface and machine learning baked right in.

It was created in 2008 by Vsevolod Stakhov, a Russian engineer who looked at SpamAssassin and went, “love the idea, hate the speed, let me rewrite this from scratch.” The “r” stands for “rapid.” It is, and honestly, the man delivered.

A brief, slightly unhinged history of spam

Before we praise rspamd, we have to understand the enemy. And the enemy has a long, embarrassing résumé.

1978: The original sin, Gary Thuerk

The very first spam email was sent on 3 May 1978 by a marketing manager at Digital Equipment Corporation named Gary Thuerk. He blasted a product announcement to 393 people on ARPANET, the proto-internet that connected universities and the US Department of Defense. Reception was, shall we say, chilly. People were furious. One government rep called him personally to yell at him. Gary defended himself for the rest of his life. He claims he generated $13 million in sales. He also claims to be “the father of spam,” which is genuinely the worst LinkedIn bio of all time.

1993: The word “spam” is born

The term itself comes from a Monty Python sketch where Vikings sing “spam, spam, spam, spam” over and over until you cannot hear anything else. In 1993, a Usenet admin named Joel Furr used the word for an accidental mass-post on the alt.religion newsgroup. It stuck. So yes, every time you say “spam,” you are quoting British comedians in horned helmets. The internet is a beautiful place.

1994: The Canter and Siegel incident

Two American lawyers, Laurence Canter and Martha Siegel, posted an advertisement for their immigration services to every single Usenet newsgroup. Six thousand of them. People lost their minds. They received death threats, their fax machine was overwhelmed (people would dial it and leave the line open for hours, the original DDoS), and their internet provider’s servers crashed. They wrote a book about it afterwards. Of course they did.

2003: The CAN-SPAM Act

The US Congress finally passed the CAN-SPAM Act (Controlling the Assault of Non-Solicited Pornography And Marketing, yes that is the real name, government acronyms are a hate crime). It required commercial emails to have an unsubscribe link, a real sender address, and no deceptive subject lines. Critics called it “the You Can Spam Act” because it actually legalised a lot of bulk marketing as long as you ticked the boxes. Hard agree, honestly.

The lawsuits and the lawsuits and the lawsuits

Spammers have been sued into oblivion repeatedly. Some greatest hits:

• MySpace v. Wallace (2008): Sanford Wallace, “the Spam King,” was hit with a $234 million judgment.
• Facebook v. Wallace (2009): same guy, again, $711 million.
• Facebook v. Guerbuez (2008): Adam Guerbuez fined $873 million for spamming Facebook. He never paid. He was banned from Facebook for life, which is honestly the better punishment.
• Microsoft v. Soloway (2007): Robert Soloway, the original “Spam King,” went to prison for nearly four years.

None of this actually stopped spam. It just moved offshore. Today the spam industry is run from data centres in Eastern Europe, Southeast Asia, and increasingly from poorly secured smart fridges. Yes, your fridge. We will get to that.

What’s actually in your spam folder (and why it’s terrifying)

Spam is not just annoying anymore, it is the front line of every major cybercrime category. Here is the modern menu of threats:

• Phishing: “Your Netflix account has been suspended, click here.” Designed to steal passwords. Targets your mum, succeeds depressingly often.
• Spear phishing: Like phishing, but personalised. “Hi Sarah, attached is the Q2 invoice as discussed.” Sarah does not remember discussing it. Sarah clicks anyway.
• Business Email Compromise (BEC): Hackers impersonate your CEO and tell finance to wire $80,000 to a vendor account. The FBI says BEC has caused over $50 billion in losses since 2013. With a B.
• Malware droppers: Innocent-looking PDFs and Word docs full of macros that install ransomware. Pays the spammer’s mortgage.
• Sextortion: “I hacked your webcam and recorded you, send Bitcoin.” Usually a complete bluff, but the volume is so high that even a 0.01% success rate is profitable.
• Pump-and-dump: Fake stock tips designed to inflate penny-stock prices so the spammer can sell. Still alive and well in 2026.
• The classic 419 scam: A Nigerian prince needs help moving $25 million. He will give you 30%. Spoiler: he will not.

This is why a good spam filter is not “a nice to have.” It is the seatbelt of the internet. Strap in.

Meet Spamhaus, the spam police

Before we get into rspamd’s clever tricks, you need to know about Spamhaus. Founded in 1998 in London by Steve Linford, Spamhaus is a non-profit, slightly mysterious, weirdly powerful organisation that maintains the world’s most-used blocklists. They track spammers, botnets, and hijacked IP addresses, and publish lists like:

• SBL (Spamhaus Block List): known spam-source IPs.
• XBL (Exploits Block List): hijacked machines and open proxies.
• PBL (Policy Block List): IPs that should never be sending mail directly (think: residential broadband).
• DBL (Domain Block List): spammy domains.
• ZEN: the combined “give me everything” list. Used by basically every major mail provider.

Roughly 80% of the world’s email servers consult Spamhaus before delivering a message. If you end up on their list, your mail does not get delivered. Anywhere. To anyone. They are the bouncer’s bouncer.

Naturally, spammers hate them. In 2013, a Dutch hosting company called Cyberbunker launched what was at the time the largest DDoS attack in history, peaking at 300 Gbps, against Spamhaus. The internet itself noticeably slowed down. Spamhaus survived. The Cyberbunker guy went to prison. Iconic.

How rspamd thinks: the scoring system

Here is the secret sauce. Rspamd doesn’t say “spam!” or “not spam!”, it says “this email looks kind of spammy, give it a score.” Each suspicious trait adds (or subtracts) points. At the end, if the total crosses a threshold, the email is rejected, tagged, or quarantined.

     Email arrives
          │
          ▼
  ┌───────────────┐
  │  rspamd runs  │
  │  ~200 checks  │
  └───────┬───────┘
          │
          ▼
   ┌──────────────┐
   │  Final score │
   └──────┬───────┘
          │
   ┌──────┼───────┬─────────────┐
   ▼      ▼       ▼             ▼
 < 4   4 to 6   6 to 15        > 15
DELIVER  TAG    GREYLIST    REJECT
 ✅ 💌  📬 [SPAM]  ⏸️ wait    🚫 bye

The thresholds are configurable. Every check, DNS blacklist hit, weird headers, suspicious URL, Bayesian probability, contributes a few points. It is essentially a giant, fast, parallel jury deliberation. Beautiful, right?

The Bayesian classifier, rspamd’s nosy housekeeper

Let’s talk about Bayesian filtering, because it is genuinely beautiful maths dressed up as common sense. The idea was popularised for spam by Paul Graham in his 2002 essay “A Plan for Spam,” and the maths goes back to Reverend Thomas Bayes in the 1700s. Yes, a vicar invented modern spam filtering. Christianity wins.

Here is how it works, in girls-night-in language: every word in an email gets a probability. The word “Viagra” appears in 92% of spam and 1% of real mail, so its spam-score is very high. The word “meeting” appears in 5% of spam and 60% of real mail, so its spam-score is very low. Rspamd multiplies up all the probabilities (using a clever combining function called Robinson’s method, then Fisher’s chi-square test), and out pops a final number between 0 and 1: how likely this email is spam.

The genius part: it learns from you. Every time you mark an email as spam (or as not spam), rspamd updates its word statistics. Within a few hundred messages, it knows your inbox like a slightly creepy housekeeper. The word “rspamd” in your inbox? Probably ham (the official opposite of spam, naming geniuses we are). The word “rspamd” in a stranger’s inbox? Might be spam. Personalised. Adaptive. Gorgeous.

The neural network, the new kid with the cool sneakers

Bayes is great, but it only looks at words in isolation. Spammers caught on and started writing emails that are structurally weird but word-wise innocent. So rspamd added a neural network module (rspamd-neural) around version 1.7 and it has gotten dramatically smarter every release since.

The neural net doesn’t look at words, it looks at the scores of all the other rspamd checks. So if your email has SPF=pass, DKIM=pass, but the body has 14 links, a base64-encoded PDF, comes from a brand-new domain, and the Bayesian score is 0.6… each of those is an input feature, and the neural net learns the patterns that correlate with spam. Multi-layer perceptron under the hood, trained per-server on your own traffic.

This is the part where rspamd genuinely surpasses everything else on the market. It is not just “AI-washing”, it is real, locally-trained, explainable machine learning, and it catches the weird stuff Bayes misses. Think of it as Bayes’s gen-Z niece who notices everything.

Blacklists, whitelists, and the DNS magic show

Rspamd checks every incoming email’s sending IP against dozens of DNS-based block lists (DNSBLs), also called RBLs, “Real-time Blackhole Lists.” How? With a delightfully clever DNS trick: it reverses the IP, prepends it to the blocklist’s domain, and does a normal DNS lookup. If a record exists, the IP is listed.

Example: sender IP is 1.2.3.4, list is zen.spamhaus.org. Rspamd queries 4.3.2.1.zen.spamhaus.org. Gets a reply? Bad IP. No reply? Probably fine. The whole thing takes milliseconds.

The lists rspamd ships with out of the box include:

• Spamhaus ZEN: the OG combined list.
• SORBS: Spam and Open Relay Blocking System, run by Proofpoint.
• SpamCop: community-reported spam sources.
• Barracuda BRBL: corporate-grade list.
• URIBL, SURBL: these list domains in URLs found inside spam bodies, not IPs. Brilliant trick.

And the opposite: whitelists (DNSWLs, like dnswl.org) list trusted senders, your bank, mailing lists, Google, etc., so rspamd can give them a bonus score and never flag them by accident.

Greylisting, the velvet-rope nightclub trick

This one is genius and so simple it makes me giggle every time. When a brand-new sender shows up that rspamd has never seen, it says: “Sorry, server’s busy, try again in 5 minutes.”

Real mail servers retry, that is literally what SMTP is designed to do. Five minutes later the email arrives, gets delivered, the sender is whitelisted forever. Spam-sending botnets, on the other hand, fire-and-forget, they have a million addresses to hit and no time to retry. They never come back. Bye, Felicia. This single trick blocks an enormous percentage of low-effort spam at essentially zero cost.

The hash-sharing networks: Pyzor, Razor, DCC

Now we get to my favourite chapter, collaborative anti-spam. Picture this: a million people get the same scammy email. If one person reports it, everyone benefits. That is the whole idea behind these three legendary hash-sharing networks, and rspamd talks to all of them.

Pyzor

Pyzor is a Python-based, open-source collaborative spam database. It takes the body of every email, calculates a “digest” (a normalised hash that survives small changes, typo fixes, name substitutions), and looks it up against a public server. If thousands of other people have already received the same body and reported it as spam, Pyzor returns a high “count” and rspamd adds points. Crowd-sourced trust. Honestly, beautiful.

Razor (Vipul’s Razor)

Created by a guy named Vipul Ved Prakash in the early 2000s and now run by Cloudmark, Razor does the same trick but with a smarter fingerprinting algorithm called “Nilsimsa.” Nilsimsa is a “locality-sensitive hash”, meaning emails that are almost the same produce almost the same hash. So spammers who randomise a few words to dodge filters? Razor still catches them. Take that, Brad.

DCC

DCC stands for Distributed Checksum Clearinghouses. Created in 2000 by Rhyolite Software, DCC is the biggest of the three by volume. It works by counting how many copies of an email have been seen across all participating servers, bulk mail is suspicious by definition. Even if every recipient consented (a legit newsletter), DCC will see “5 million copies sent, 0 reported as spam” and let it through. The wisdom of the crowd at internet scale.

OLEFY, the macro-malware detector

Last but not least: OLEFY. This one is a special-purpose tool that scans Microsoft Office attachments (the OLE file format, .doc, .xls, the old binary formats your boomer uncle still uses) for malicious macros. It is built on top of oletools and tells rspamd: “this Word document contains a VBA macro that auto-runs PowerShell on open.” That is a “burn the email” signal if I have ever seen one. Rspamd happily complies.

SPF, DKIM, DMARC, ARC, the alphabet soup of trust

Rspamd also runs all the modern email-authentication checks:

• SPF (Sender Policy Framework): asks: “Is this IP actually allowed to send mail for this domain?” Domain owners publish a list in DNS. Rspamd checks it.
• DKIM (DomainKeys Identified Mail): the sending server cryptographically signs the email. Rspamd verifies the signature against the public key in DNS. If it has been tampered with, BOOM, points.
• DMARC: combines SPF and DKIM, and tells receivers what to do if both fail (“reject”, “quarantine”, “report”). It is the policy layer.
• ARC (Authenticated Received Chain): for forwarded mail. Lets each hop add its own signature so the chain of trust survives. Beautifully nerdy.

Together, these four are the reason a spammer can no longer trivially forge “from: ceo@yourcompany.com.” Rspamd uses all of them. The result? Phishing that pretends to be from your bank gets caught at the door.

The web UI, and yes, it is genuinely cute

Most mail tools are aggressively ugly. SpamAssassin’s “interface” was a config file. Postfix is just logs. Rspamd, on the other hand, ships with a full web interface at http://localhost:11334 that shows real-time stats, lets you scan an email by pasting it into a textbox, train Bayes by clicking buttons, view history, edit symbols and scores, and visualise traffic. It is genuinely pleasant. The first time I saw it I emailed Vsevolod a thank-you. I am not exaggerating.

Installing rspamd on Debian/Ubuntu (the easy version)

If you already set up our Postfix + Dovecot guide, adding rspamd is a 5-minute job:

# Add the official rspamd repository
apt install -y lsb-release wget gpg
wget -O- https://rspamd.com/apt-stable/gpg.key | \
  gpg --dearmor > /etc/apt/keyrings/rspamd.gpg
echo "deb [signed-by=/etc/apt/keyrings/rspamd.gpg] \
  http://rspamd.com/apt-stable/ $(lsb_release -cs) main" \
  > /etc/apt/sources.list.d/rspamd.list

apt update && apt install -y rspamd redis-server

# Plug it into Postfix as a milter
postconf -e "smtpd_milters = inet:localhost:11332"
postconf -e "milter_protocol = 6"
postconf -e "milter_mail_macros = i {auth_type} {auth_authen}"
postconf -e "milter_default_action = accept"

systemctl restart rspamd postfix

That’s it. Open http://your-server:11334, set a password in /etc/rspamd/local.d/worker-controller.inc, and you have a fully working modern spam filter with Bayes, neural networks, all the major RBLs, SPF/DKIM/DMARC, Pyzor/Razor/DCC (after a small extra install), and OLEFY. The defaults are sane. Honestly, this is the most “it just works” piece of mail-server software I have ever installed.

Frequently asked questions

Is rspamd really better than SpamAssassin?

For modern workloads, yes, by a country mile. Rspamd is written in C with Lua plugins; SpamAssassin is Perl. On the same hardware, rspamd is typically 5–10× faster, uses less memory, has built-in neural-network support, and a real web UI. SpamAssassin still has the bigger rule community, but rspamd has caught up and is now the default in iRedMail, Mailcow, Mail-in-a-Box, and most modern mail stacks.

Do I have to train the Bayesian classifier myself?

Yes, eventually, but only a little. Rspamd’s defaults catch 90% of obvious spam without any training. Train Bayes when you have ~200 messages each of ham and spam to feed it, and accuracy will climb above 99%. You can train via the web UI, by piping messages to rspamc learn_spam, or by configuring Dovecot to auto-train when you drag an email into the Junk folder. The third option is the chef’s kiss.

Will rspamd ever quarantine legitimate email by accident?

Out of the box, false positives are very rare, somewhere around 0.1% in our experience. The scoring system is forgiving (you have to cross multiple thresholds to be rejected), and DNSWL/whitelists protect the big legitimate senders. If you do get a false positive, you can retrain Bayes against it, add the sender to a local whitelist, or lower a specific symbol’s weight in /etc/rspamd/local.d/.

How much RAM does rspamd need?

For a small home or hobby server, 512 MB is plenty. For a busy mailing-list operator handling a million emails a day, plan for 2–4 GB plus Redis. Compared to SpamAssassin’s classic ~150 MB per spamd child process, rspamd’s memory model is dramatically more efficient because it uses async I/O and a fixed number of workers.

Does rspamd help with outgoing spam too?

Yes, and this is hugely underrated. You can configure rspamd to scan outbound mail as well, which catches compromised accounts on your server before they ruin your reputation and get you on Spamhaus. A single hacked WordPress account can blacklist your entire domain in 24 hours. Outbound scanning is the seatbelt for that scenario. Set actions = { reject = 15; soft_reject = "Rate limit exceeded"; } and you are golden.

Can I use rspamd without Redis?

Technically yes, but you’d be giving up Bayesian classifier persistence, greylisting state, neural-network learning, and rate-limiting. Just install Redis. It is one apt command. Or even better, install our hardened Valkey package, Redis-compatible, BSD-licensed, and faster.

Related reading

• Postfix + Dovecot Mail Server Setup on Debian 12 and 13 (2026 Guide): the full mail-server stack rspamd plugs into. Start here if you do not have a working Postfix yet.
• Valkey Explained: The Redis Fork That Actually Won: what to use as rspamd’s key-value backend in 2026. Faster, BSD-licensed, and packaged on deb.myguard.nl.
• How to Install ModSecurity and OWASP CRS on NGINX: rspamd defends mail, ModSecurity defends the web. Both belong on the same server.
• WordPress Hardening Plugin for ModSecurity CRS: stop the compromised-WordPress-account-spams-the-world scenario before it starts.

That is your evening. Pour another glass, install rspamd, watch the spam disappear. You can thank Vsevolod and Reverend Bayes later. 💌

What is Valkey, in plain English?

Imagine your website is a busy coffee shop. Every time someone orders a latte, your barista (the database) has to grind beans, steam milk, foam, pour, and add the little heart on top. That’s slow. Now imagine you keep a tray of pre-made lattes on the counter, when someone orders one, you just hand it over. That tray is a cache, and Valkey is the tray. It holds frequently-needed data in memory so your apps don’t have to go grind the beans every time.

Technically: Valkey is an in-memory, network-accessible key-value database. You give it a key (“user:42:cart”), it gives you back the value (“3 lattes, 1 muffin”). It’s blisteringly fast, a single instance comfortably handles 100,000+ operations per second on a modest VPS. It speaks the Redis wire protocol, so anything that talks to Redis talks to Valkey unchanged. Drop it in, walk away.

Wait, isn’t this just Redis?

This is where it gets juicy. In March 2024, the company that owns Redis suddenly changed the licence from open-source BSD to a more restrictive “source-available” licence (SSPL / RSALv2). Translation: free to use, but legally hostile to anyone running it as a service for customers. The open-source community did what the open-source community always does when this happens, they forked.

Within a week, the Linux Foundation, AWS, Google Cloud, Oracle, Ericsson, and Snap had launched Valkey: a clean fork of the last freely-licensed Redis (7.2.4), with the original BSD-3-Clause licence intact, governed by a vendor-neutral foundation. Debian, Ubuntu, Fedora, and Alpine all switched their default “redis” package to Valkey within months. AWS ElastiCache replaced Redis with Valkey on managed services. By the time Redis tried to walk back the licence change in 2025, Valkey already had more contributors than Redis itself.

So when you install valkey in 2026, you’re not getting some hobbyist experiment. You’re getting the actual, mainstream, foundation-backed continuation of Redis, with bug fixes, performance work, and security patches that Redis never received. It’s Redis, minus the corporate drama.

What people actually use Valkey for

• WordPress object cache. Plugins like Redis Object Cache, W3 Total Cache, and LiteSpeed Cache all talk to Valkey unchanged. The result: 50-90 % fewer database queries on every page load, and a noticeably snappier admin dashboard. If you’ve ever clicked “Save” in WordPress and waited an awkward two seconds, Valkey kills that.
• Session storage. PHP, Node.js, Rails, Django: all of them can keep user sessions in Valkey instead of files. That means session data survives across multiple web servers (essential for load balancing) and doesn’t fill up your disk with millions of one-kilobyte files.
• Rate limiting. “Don’t let this IP make more than 60 API requests per minute.” Valkey does this in a single atomic operation. Cloudflare-grade rate limiting on your own server, basically free.
• Job queues. Background tasks (sending email, processing uploads, generating thumbnails) go onto a Valkey list, a worker pulls them off. Sidekiq, BullMQ, RQ, Laravel Horizon: they all run on Valkey.
• Leaderboards and counters. Sorted sets in Valkey let you maintain “top 100 most active users today” with one command per update. Used by every gaming site you’ve ever loved.
• Pub/sub messaging. A lightweight message bus between microservices, without dragging in Kafka or RabbitMQ.

Why use our Valkey package and not the stock Debian one?

Debian’s Valkey package is fine. It’s also frozen, once Debian 13 (Trixie) shipped, the Valkey version baked into it is the version you’ll have for the next two years unless you do something about it. Meanwhile upstream Valkey keeps shipping releases with real performance wins and security fixes every few weeks.

Our build at deb.myguard.nl tracks upstream Valkey 9.1.0 (the current stable release as of May 2026) and rebuilds within hours of every new tag. But that’s only half the story, the package itself ships a bunch of operational improvements that the Debian package doesn’t have:

1. Compiled for performance, not lowest-common-denominator

We build Valkey with Link-Time Optimization (LTO), -O3, -fno-plt, and -fno-semantic-interposition. In plain English: the compiler is allowed to inline aggressively across translation units, skip a layer of indirection on every function call, and reorder code for the modern CPUs you’re actually running on. The throughput gain over a stock -O2 build is real, typically 5-12 % on the standard valkey-benchmark SET/GET workload, sometimes more on pipelined operations.

2. Compiled for security, with FORTIFY_SOURCE level 3

Every Debian hardening flag is on (hardening=+all: stack protector, stack-clash protection, RELRO, BIND_NOW, PIE, control-flow integrity), and we go one further by bumping _FORTIFY_SOURCE from 2 to 3. That enables additional compile-time and runtime checks on memory functions like memcpy, strcpy, and friends. A buffer overflow that would silently corrupt memory becomes an immediate, loud, abort-the-process crash, which is exactly what you want, because a crash is a bug report, but silent memory corruption is a data breach waiting to happen.

3. A fully hardened systemd unit out of the box

Most database services run with way too many privileges. Our valkey-server.service ships with the full systemd sandbox switched on: NoNewPrivileges=true, ProtectSystem=strict, ProtectKernelTunables/Modules/Logs, MemoryDenyWriteExecute=true, RestrictAddressFamilies limited to AF_INET/AF_INET6/AF_UNIX, an empty CapabilityBoundingSet, SystemCallFilter=@system-service, and NoExecPaths=/ (so the daemon literally cannot execute any binary other than itself). If somebody finds a remote code execution in Valkey tomorrow, the blast radius on our package is “they get to run code as the valkey user inside a near-empty namespace with no network families they don’t already have.” On a stock build it’s “they get a shell.”

4. A drop-in /etc/valkey/conf.d/ directory

The main valkey.conf is a 2,000-line conffile and you don’t want to edit it. Every time you do, the next package upgrade fights you over conffile changes. Our package ships an include /etc/valkey/conf.d/*.conf line in the main config, plus an empty drop-in directory. Want to set maxmemory 2gb and switch the eviction policy? Drop a one-line file in /etc/valkey/conf.d/10-memory.conf and reload. Survives upgrades, easy to manage with Ansible/Salt/Puppet, easy to diff in version control.

5. An AppArmor profile (when AppArmor is available)

Belt and braces alongside the systemd sandbox: a Mandatory Access Control profile at /etc/apparmor.d/usr.bin.valkey-server that confines reads to /etc/valkey and writes to /var/lib/valkey / /var/log/valkey / /run/valkey. Loaded automatically on systems that support it, silently skipped in containers that don’t. You get defense in depth on Ubuntu (where AppArmor is on by default) without any breakage on hosts without it.

6. Sane kernel tuning, applied automatically

Valkey emits two warnings on every fresh install on a stock kernel: “vm.overcommit_memory is not set to 1” and “the TCP backlog setting was lowered to 128 because /proc/sys/net/core/somaxconn is set to the lower value.” Annoying, and they actually do affect throughput. We ship /usr/lib/sysctl.d/30-valkey-server.conf that fixes both. Applied automatically by systemd-sysctl on next boot, or by the postinst when you’re inside a Docker container without systemd.

7. A built-in healthcheck binary

We ship /usr/bin/valkey-healthcheck, a tiny wrapper that returns exit code 0 if the server replies to PING, 1 if it doesn’t. Wire it into a Docker HEALTHCHECK, a Kubernetes liveness probe, a Nagios/Icinga check, a systemd watchdog, anything that wants a binary that says “yes the service works” or “no it doesn’t.” Honours the same env vars as valkey-cli (host, port, TLS, auth), so it works regardless of how exotic your deployment is.

8. Works perfectly inside Docker (without systemd or AppArmor)

All of the above is built so the package installs cleanly inside a minimal Debian/Ubuntu container. No hard dependency on systemd, no hard dependency on AppArmor, no failed postinst when those subsystems aren’t around. The systemd unit and the AppArmor profile become inert files, present but not enforced, and the sysctl drop-in is applied at install time instead of at boot. Same package, two deployment models, zero ceremony.

How to install Valkey from our repository

If you haven’t added the deb.myguard.nl repository yet, that takes about ninety seconds, there’s a one-page setup guide that handles the GPG key and APT source. Once that’s in:

sudo apt update
sudo apt install valkey-server valkey-tools

# Enable on boot (skip inside Docker)
sudo systemctl enable --now valkey-server

# Check it answers
valkey-healthcheck && echo "Valkey is up"

That’s it. You now have a hardened, performance-tuned, foundation-backed Redis replacement listening on 127.0.0.1:6379.

Migrating from Redis: how painful is it?

Pretty close to zero pain. Valkey speaks the same wire protocol as Redis, ships the same commands, returns the same replies. RDB and AOF persistence files from Redis 7.2 load unchanged. The CLI tool is valkey-cli instead of redis-cli, but both are symlinked on most distros, and they accept identical arguments.

Practical migration recipe: stop Redis, copy dump.rdb to /var/lib/valkey/dump.rdb, chown valkey:valkey it, start Valkey, point your app at localhost:6379 instead of wherever Redis was. Done. PHP’s phpredis extension, Python’s redis-py, Node.js’ ioredis, Go’s go-redis, all of them connect to Valkey without a single code change.

A WordPress-specific recipe

Since most readers of this site run WordPress, here’s the exact recipe to turn Valkey into a WordPress object cache. Install Valkey as above, then drop this into /etc/valkey/conf.d/10-wordpress.conf:

maxmemory 256mb
maxmemory-policy allkeys-lru
save ""
appendonly no

That tells Valkey: use up to 256 MB of RAM, evict the least-recently-used keys when full, and don’t bother persisting to disk (it’s a cache, if it dies, WordPress just rebuilds it from MySQL). Restart with systemctl restart valkey-server, install the Redis Object Cache plugin in WordPress, click “Enable Object Cache.” Done. Your admin dashboard just got 3-5× faster, and the MySQL load on your server dropped by half.

Frequently Asked Questions

Is Valkey really free? Like, free-free?

Yes. BSD 3-Clause licensed, governed by the Linux Foundation, with no contributor licence agreement that hands rights to a corporation. You can use it commercially, modify it, redistribute it, run it as a service, embed it in proprietary products. The whole point of the fork was to keep it that way permanently.

Should I uninstall Redis if I have it?

Eventually, yes. Both can coexist (different default ports if needed), but there’s no reason to run both long-term. Migrate the data over, point apps at Valkey, then remove the Redis package. If you’re on Debian 13 or Ubuntu 24.04+ you may notice apt already wants to replace Redis with Valkey on the next upgrade, that’s the distribution doing the same migration for you.

How much RAM does Valkey need?

Whatever you tell it. For a WordPress object cache, 128-256 MB is plenty. For a session store on a busy site, 512 MB-1 GB. For a primary database with millions of keys, size it to fit your working set in memory. The base process itself uses about 5 MB, almost nothing. Always set maxmemory; never let Valkey grow unbounded.

Does Valkey lose data if the server reboots?

By default it snapshots to disk every few minutes (RDB persistence) and optionally appends every write to an AOF log for crash safety. You can disable persistence entirely (good for pure caches), enable both (good for primary databases). The trade-off is durability vs. write performance, and it’s a single config flag away in either direction.

Is Valkey faster than Redis?

In raw single-threaded SET/GET, they’re within noise of each other, they share an ancestor. Where Valkey pulled ahead is in multi-threaded I/O (enabled by default in 9.0+, on by default on multi-core systems) and in the steady stream of optimizations the wider contributor base has been merging. On the same hardware, a recent Valkey will out-throughput a Redis 7.2 by 20-40 % on multi-connection workloads. Our build with -O3 and LTO adds a few more percent on top.

What’s the catch?

Honestly, none for most use cases. If you used a Redis Enterprise feature (Redis Stack modules like RedisJSON, RedisSearch, RedisBloom) then those modules were proprietary and aren’t in Valkey core. The good news: Valkey has its own first-party equivalents (valkey-json, valkey-search, valkey-bloom) which are now stable and shipping. We’ll likely add packages for those next.

Related reading

• WordPress NGINX Configuration: PHP-FPM Tuning, FastCGI Cache and Redis (2026 Guide): the full stack guide that puts Valkey (still named “Redis” in the plugin world) into context for WordPress hosting.
• Database Boost: Free WordPress Database Optimization Plugin: pairs nicely with Valkey object caching to keep MySQL lean.
• How to Add the myguard APT Repository: the ninety-second setup for the repo this package lives in.
• Full package catalogue: every package we ship, with one-line descriptions.

Valkey is the future of self-hosted in-memory caching on Linux. Our build makes it faster, safer, and easier to operate than anything else in the Debian/Ubuntu ecosystem, and it stays out of your way whether you’re running it on bare metal, in a VM, or inside a Docker container. Install once, forget about it for years.

What Is Vaultwarden, in Plain English?

Imagine a tiny, very polite digital butler whose entire job is to remember every password you’ve ever made, autofill them when you visit the right website, and gently scold you when you try to reuse one. That’s a password manager. The most famous one is Bitwarden, it’s open-source, audited, and trusted by millions. But the official Bitwarden server is a beast: it needs Microsoft SQL Server, multiple containers, lots of RAM, and frankly a degree in patience to keep running on your own hardware.

Vaultwarden is the lightweight, community-built alternative server. It speaks the same language as Bitwarden, meaning every official Bitwarden app, browser extension, and CLI tool works with it perfectly, but it’s written in Rust, fits in a single tiny Docker container, sips about 50 MB of RAM, and runs happily on a Raspberry Pi, a cheap VPS, or that old laptop gathering dust in your closet. It used to be called “Bitwarden_RS,” but the name was changed (politely, at the official Bitwarden company’s request) to avoid confusion. Same engine, different badge.

The project is fully open-source under the AGPLv3 license and developed in the open on GitHub. If you want to dig deeper, star the repo, read the source, or file a bug, here are the official links:

• GitHub repository: github.com/dani-garcia/vaultwarden: source code, releases, issues.
• Project wiki: github.com/dani-garcia/vaultwarden/wiki: the definitive documentation, with deep dives on every config flag, reverse-proxy examples, backup recipes, and fail2ban jails.
• Docker Hub image: hub.docker.com/r/vaultwarden/server: the official container we’ll be pulling.
• Bitwarden (the upstream protocol & clients): bitwarden.com: the company whose API Vaultwarden re-implements.

So when we say selfhosted Vaultwarden, we mean: you run the server, you own the encrypted vault, you control who can sign up, and nobody, not Bitwarden Inc., not Google, not your nosy ISP, gets to peek at your data. The vault is end-to-end encrypted on your device before it ever touches the server. Even you, the server admin, can’t read your users’ passwords. That’s the magic.

Everything Is Encrypted Server-Side, Even the Admin Can’t See It

Read this section twice. This is the single most important thing to understand about Vaultwarden, and the reason it’s safe to self-host in the first place.

When you type your master password into the Bitwarden client, that password never leaves your device. Instead, the client uses it (via PBKDF2 with 600,000 iterations, or Argon2id in newer setups) to derive an encryption key. That key encrypts every single field in your vault, passwords, notes, TOTP secrets, attachments, passkeys, the lot, using AES-256-CBC with an HMAC-SHA256 integrity check. Only the encrypted blob is sent up to the server.

What does this mean in practice?

• The server stores ciphertext only. If you peek at the Vaultwarden SQLite database with sqlite3 /data/db.sqlite3, you’ll see rows of base64 gibberish like 2.aGsmaiq…|wQjT…|3kPq…. That’s it. No readable passwords, no readable URLs, nothing.
• The administrator (you, or whoever runs the server) cannot read anyone’s vault. Not yours. Not your family’s. Not a colleague’s. The server literally lacks the key. This is called zero-knowledge or end-to-end encryption, and it’s the same model as Signal, ProtonMail, and the official Bitwarden cloud.
• A full server compromise leaks ciphertext, not plaintext. Even if an attacker dumps the database, the volume, and the RAM, they walk away with encrypted blobs and a hashed authentication token. They’d still need to brute-force every individual user’s master password to read anything: and with a strong passphrase that’s astronomically expensive.
• The /admin panel can manage users, invitations, and config: but cannot view vault contents. It’s an ops console, not a backdoor.

This is genuinely brilliant and genuinely terrifying. Because of zero-knowledge encryption, there is exactly one rule that follows from it, and it has no exceptions:

If you forget your master password, your vault is gone. Forever. There is no recovery.

Let me be very clear about what that means. There is no “forgot password” email. There is no admin override. There is no support ticket that ends with someone resetting it for you. The server can’t help you, because the server cannot read your vault. That’s the whole point. If it could help you, it could help an attacker too.

The admin can delete your account and let you start over with an empty vault. They cannot recover the data inside it. Years of saved passwords, TOTP secrets, passkeys, attachments, all of it instantly worthless ciphertext. You are, in the most literal sense, on your own.

So before you put a single password into Vaultwarden:

• Write your master password on paper. A long passphrase like “correct-horse-battery-staple-violet-piano”. Put it in a sealed envelope in a safe, or a fireproof box, or with a trusted relative. Yes, paper. Welcome to 2026.
• Set up Emergency Access with a person you’d trust to inherit your digital life. They request access, you have N days to deny, after that they get a one-time copy.
• Generate and store a few recovery codes if you enable 2FA on the vault: losing 2FA is just as fatal as losing the master password.
• Test your backups. Once a year, restore them to a sandbox container and log in. A backup you’ve never tested is a hope, not a backup.

Get those four things right and zero-knowledge encryption is your friend. Skip them and one bad morning, you’ll be that person on Reddit asking “is there any way to recover my Vaultwarden?” The answer will always be no.

Why run self-hosted Vaultwarden at all?

Fair question. The cloud version of Bitwarden is excellent, audited, and either free or absurdly cheap. So why bother running your own?

• Total control. Your passwords never live on someone else’s hardware. If a cloud provider gets breached (it happens: ask LastPass), you’re not in the blast radius.
• No subscription fees. Vaultwarden gives you every paid Bitwarden feature for free: 2FA codes (TOTP), file attachments, organizations, Bitwarden Send, emergency access, the lot.
• Privacy. No telemetry, no analytics, no “anonymous usage data.” Just you and your encrypted blob.
• Learning. If you’re a tinkerer or sysadmin, running Vaultwarden teaches you Docker, reverse proxies, TLS, and backups: all skills that pay rent in the real world.
• Family & team sharing. Spin up an organization, invite the household, share the Wi-Fi password and the Disney+ login. Built-in.

The trade-off? You are now responsible for uptime, backups, and security. If your server dies and you didn’t back up, your vault is gone. So read the backup section twice. I’m not joking.

The Vaultwarden Docker Image: Small, Fast, Friendly

The official Vaultwarden Docker image lives at vaultwarden/server on Docker Hub, and is built straight from the upstream GitHub repository. It’s a single static Rust binary plus the bundled web vault frontend, weighing in at roughly 180 MB on disk. At runtime it uses 30–80 MB of RAM depending on how many users you have. Compare that to the official Bitwarden self-host stack, which routinely chews through 2–3 GB. It’s a tiny footprint.

The image ships with sensible defaults: SQLite storage (great for small deployments), bundled web vault, optional WebSocket support for live sync, and a built-in admin panel you can enable for managing users. For bigger setups, you can switch the storage backend to MySQL/MariaDB or PostgreSQL, both are supported out of the box.

What You Get Out of the Box

• End-to-end encrypted vault: passwords, secure notes, identities, credit cards.
• TOTP / 2FA codes built into entries (no need for a separate Authy/Google Authenticator).
• File attachments: store passport scans, license PDFs, encrypted at rest.
• Bitwarden Send: send a password or file to someone via a one-time, self-destructing link.
• Organizations & collections: share vault items with family, teams, or per-project.
• Emergency access: let a trusted person request access to your vault if you’re, well, hit by a bus.
• Admin panel at /admin for invitations, user management, and config.
• Web vault served right from the same container: no separate frontend container needed.
• Yubikey, Duo, and WebAuthn 2FA support for your login itself.

TOTP, 2FA and Passkeys, The Headline Features

Passwords alone are not enough anymore. Every serious account should have a second factor, and increasingly, no password at all. Vaultwarden is genuinely brilliant at all three: it can store your TOTP codes, protect the vault itself with multiple 2FA methods, and now sync your passkeys across every device. Let’s unpack each.

Built-in TOTP Code Generator (Authenticator Replacement)

TOTP (Time-based One-Time Password) is that six-digit code that changes every 30 seconds, the thing Google Authenticator, Authy, and Microsoft Authenticator show you. The dirty secret? It’s just a tiny shared secret + the current time, run through HMAC-SHA1. Any app can generate them, including Vaultwarden.

When you add a login entry, there’s a field labelled Authenticator Key (TOTP). Paste the otpauth:// URI from a QR code (or just the base32 secret) and from that moment on, the Bitwarden client shows the live 6-digit code right under the username and password, with a little countdown circle. Autofill on the login page fills the password and the TOTP code automatically. No more juggling your phone.

Why this is huge:

• One app instead of two. Bin Authy / Google Authenticator. One unlock, all your codes.
• Synced across devices. Lose your phone? Your codes are safe in your encrypted vault on every other device.
• Backed up automatically. Whatever backs up your vault backs up your TOTP secrets too. (Old-school Authenticator users know that “I lost my phone” used to mean “I lost all my 2FA accounts.”)
• Steam Guard support. Vaultwarden also generates Steam’s funky 5-character codes: paste a steam:// URI.

There’s a mild philosophical argument that storing your password and your 2FA code in the same vault defeats some of the point of 2FA. That’s true if your master password gets brute-forced. In practice, with a strong master password + the vault itself protected by 2FA (next section), the combined security is dramatically higher than “weak reused password + SMS code.” Pick your threat model.

2FA for the Vault Itself

“Wait, I can put 2FA on the vault that holds my 2FA codes?” Yes. And you absolutely should. If someone steals your master password, the 2FA prompt at login is your last line of defence. Vaultwarden supports five different second factors, configured per-user from the web vault under Settings → Two-step Login:

• Authenticator app (TOTP): the classic: scan a QR with any TOTP app. Use a different app than Vaultwarden itself (e.g. your phone’s built-in iOS/Android authenticator), otherwise you’ve locked yourself out if the vault is down.
• Email codes: a 6-digit code mailed to you on login. Requires SMTP configured in the container (SMTP_HOST, SMTP_FROM, etc.).
• YubiKey OTP: tap your YubiKey, done. Up to five keys per account. Free YubiKey 5-class hardware tokens are the gold standard.
• FIDO2 / WebAuthn: any modern security key (YubiKey, SoloKey, Nitrokey, even your phone’s secure enclave). Phishing-resistant by design: the browser checks the domain for you.
• Duo Security: for organisations already paying Cisco for Duo. Push notification to the Duo mobile app.

Bitwarden’s hosted service paywalls YubiKey and Duo behind the Premium tier. On self-hosted Vaultwarden, every single 2FA method is free. That alone covers the €40/year Premium subscription you’d otherwise pay.

A small but important config flag: set EMAIL_2FA_ENABLED=true only if SMTP is reliable. If your mail relay dies, users can’t log in. WebAuthn + a recovery code printed to paper is the lowest-friction combo for most households.

Passkeys, the (Genuinely) Password-Free Future

Passkeys are the new shiny. They’re cryptographic key-pairs (FIDO2/WebAuthn under the hood) stored on your device that let you log in to websites with a fingerprint or face scan, without ever typing a password. The site stores only the public key; the private key never leaves your device. No password to phish, no password to leak, no password to remember. It is genuinely the biggest leap forward in auth in 20 years.

The catch with Apple/Google/Microsoft passkeys: they’re locked to their ecosystems. Use an iPhone? Your passkeys live in iCloud Keychain. Switch to Android? Good luck. This is exactly the kind of vendor lock-in that self-hosting fixes.

Recent Vaultwarden releases (from server v1.32+ paired with the modern Bitwarden clients) implement passkey storage in the vault. That means:

• Create a passkey on any site (GitHub, Google, Microsoft, Amazon, Best Buy, hundreds more) and Vaultwarden offers to save it: same dialogue as saving a password.
• Sync across every device. The passkey created on your Windows laptop is instantly usable on your Android phone, your iPad, your Linux desktop. One vault, every platform.
• End-to-end encrypted in the same vault as your passwords: server admin can’t read them.
• No iCloud, no Google Account, no Microsoft Account required. You own the keys.
• Log in to Vaultwarden itself with a passkey: the “Login with passkey” flow on the Bitwarden client lets you skip the master password entirely on trusted devices (still 2FA-protected for sensitive operations).

One small caveat: passkey support in Vaultwarden is still maturing. Check the project wiki for the current matrix of which client versions support creation vs. usage vs. login. Browser-extension passkey creation works today on Chrome/Edge/Firefox; mobile creation is rolling out.

Organisations & Sharing, Built for Families and Teams

Here’s where Vaultwarden quietly destroys the competition. On commercial password managers, “share with family” is a paid tier costing €40–60 a year. On self-hosted Vaultwarden, it’s free, unlimited, and frankly more flexible. The mechanism is called Organisations.

An Organisation is a shared vault. You create one (say, “Household”), invite people by email, and any item placed in the org is visible to every member. Inside the org you can carve it up further with Collections, think of them as folders with permissions. So “Streaming” (Netflix, Disney+, Spotify) might be visible to everyone, but “Finance” (bank, broker, tax portal) only to you and your partner. Kids get the streaming collection only.

• Invite by email: recipient creates a Bitwarden account on your server and accepts. (Requires SMTP configured; alternatively the admin panel can generate invite links manually.)
• Roles: Owner, Admin, Manager, User. Owners and Admins manage members and collections; Users just consume items.
• Per-collection permissions: read-only, read/write, or hide-password (members can autofill but can’t view the actual password, useful for shared employee logins).
• Move items between personal and org vaults with two clicks. No exporting/importing.
• Unlimited orgs, unlimited members, unlimited collections. The official Bitwarden Families plan caps at 6 users; on Vaultwarden, invite the whole village.

Practical patterns we see all the time on instances like vault.myguard.nl:

• “Household” org with Streaming / Bills / Wi-Fi / Insurance collections, every adult is a Manager, kids are Users on Streaming only.
• “Work” org per team: Ops, Dev, Marketing, each with their own shared service accounts.
• “Estate” org: read-only collection shared with a sibling or spouse, containing important account info, insurance policies, and recovery codes. Combined with Emergency Access (below), this is the “if I drop dead” playbook.

Sharing a Single Password or File, Bitwarden Send

Sometimes you don’t want to set up a whole org, you just need to hand one password or one document to someone, securely, once. Maybe it’s the new Wi-Fi password for a houseguest, a tax PDF for your accountant, or a server root password for a contractor doing a one-off job. Email? Insecure. WhatsApp? Sits in chat history forever. SMS? Please, no.

Enter Bitwarden Send. You create a Send (a text snippet or a file up to 500 MB), set the rules, and Vaultwarden hands you a unique URL. The recipient opens the link, sees the content once, and it’s gone. They don’t need a Bitwarden account. They don’t need to install anything. They just click.

• Text Sends: paste a password, an API key, a recovery code, a love letter. Up to 1000 characters in a clean shareable URL.
• File Sends: attach a PDF, image, ZIP, anything up to 500 MB. End-to-end encrypted; the server stores only the ciphertext.
• Expiry & max access count: “expires in 1 hour” or “max 1 view” or both. After that it self-destructs.
• Optional access password: recipient must enter a password (which you share via a different channel) to decrypt. Defeats accidental link leakage.
• Hide email: by default the Send shows your account email; toggle this off for anonymous shares.
• Manual disable: change your mind? Hit “disable” and the link dies immediately, even before expiry.

Enable Sends with SENDS_ALLOWED=true in your compose file (it’s on by default in our example above). On the client, look for the paper-plane icon. The whole flow takes about ten seconds, and you’ll never go back to pasting passwords into WhatsApp again.

Other Features Worth Knowing

• Bitwarden Send: encrypted, self-destructing links for sharing a password or file with someone who doesn’t have Bitwarden. Set an expiry, a max view count, an optional access password.
• Emergency Access: designate a “trusted contact” who can request access to your vault after a configurable waiting period. Hit-by-a-bus protection without giving anyone live access today.
• Organisations & collections: share specific items with family or a team. Granular permissions per collection.
• Vault health reports: flags reused passwords, weak passwords, exposed passwords (checked against Have I Been Pwned), and inactive 2FA on sites that support it.
• File attachments: encrypted PDFs, passport scans, recovery codes attached to entries.
• SSH keys (recent versions): store and serve SSH private keys via the Bitwarden agent. Goodbye ~/.ssh/id_rsa sitting in plaintext.

A Working Docker Compose Setup

Here’s a minimal, production-leaning docker-compose.yml that you can drop on any Linux box with Docker installed. We use a named volume for persistence, expose only to localhost, and let a reverse proxy handle TLS. (We’ll cover the proxy in a minute, and yes, our WordPress NGINX configuration guide covers the same NGINX patterns we’ll use here.)

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "false"
      INVITATIONS_ALLOWED: "true"
      ADMIN_TOKEN: "REPLACE_ME_WITH_A_LONG_RANDOM_STRING"
      WEBSOCKET_ENABLED: "true"
      SENDS_ALLOWED: "true"
      EMERGENCY_ACCESS_ALLOWED: "true"
      LOG_LEVEL: "warn"
      ROCKET_PORT: "8080"
    volumes:
      - vw-data:/data
    ports:
      - "127.0.0.1:8080:8080"

volumes:
  vw-data:

Start it with docker compose up -d and you’ve got Vaultwarden listening on port 8080 of localhost. That’s it. Seriously. The whole server is one container.

Generating a Strong Admin Token

The ADMIN_TOKEN protects the /admin panel. Don’t use a memorable password, use the Argon2 hashed form Vaultwarden recommends. Generate it with:

docker run --rm -it vaultwarden/server /vaultwarden hash

Paste a long random passphrase, copy the resulting hash, and stick it in ADMIN_TOKEN. Now even if your env file leaks, your admin panel doesn’t fall over.

Putting Vaultwarden Behind a Reverse Proxy

Vaultwarden must be served over HTTPS. The Bitwarden clients flat-out refuse to talk to a plain-HTTP server (and rightly so). The easiest way is to put NGINX (or our extended Angie build) in front and let Let’s Encrypt handle the certificate. Here’s the relevant NGINX server block:

server {
    listen 443 ssl http2;
    server_name vault.example.com;

    ssl_certificate     /etc/letsencrypt/live/vault.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vault.example.com/privkey.pem;

    client_max_body_size 525M;  # for big attachments

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket for live sync
    location /notifications/hub {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Reload NGINX, run certbot, and you’re done. Your vault is now live on https://vault.example.com, exactly like our reference instance at vault.myguard.nl.

Setting Up the Client (Browser, Phone, Desktop, CLI)

Here’s the beautiful bit. Vaultwarden is API-compatible with Bitwarden, so you use the official Bitwarden apps, they’re polished, audited, and available on basically everything. You just have to point them at your server instead of Bitwarden’s cloud.

Browser Extension (Chrome, Firefox, Edge, Safari, Brave)

1. Install the Bitwarden extension from your browser’s store.
2. Before logging in, click the little cog/settings gear at the top-left.
3. Find Self-hosted environment and set Server URL to https://vault.example.com (or https://vault.myguard.nl if you’re testing).
4. Save. Go back. Create your account or log in.

That’s it. The extension now talks exclusively to your server. It will autofill on login pages, generate strong passwords, save new logins automatically, and warn you if you reuse one.

Mobile (iOS & Android)

1. Install Bitwarden from the App Store / Play Store.
2. On the very first screen, tap the gear icon (top-left).
3. Pick Self-hosted and enter your server URL.
4. Log in. Enable biometrics (FaceID / fingerprint) for instant unlock.
5. Turn on Autofill Services (Android) or AutoFill Passwords (iOS settings).

From now on, every login screen on your phone offers you the right credentials with a tap.

Desktop App

The Bitwarden desktop app is available for Windows, macOS, and Linux (including a Snap and Flatpak). Same routine: open settings before logging in, pick self-hosted, paste your URL, log in. It also unlocks the browser extension via native messaging, type your master password once, and every browser on the machine unlocks automatically.

Command Line (bw CLI)

For scripts, CI/CD, and terminal addicts, there’s bw:

npm install -g @bitwarden/cli
bw config server https://vault.example.com
bw login you@example.com
export BW_SESSION=$(bw unlock --raw)
bw list items --search github

Now you can pipe secrets into Ansible, GitHub Actions, or anywhere else without baking them into the repo. Combine this with our WordPress hardening plugin for an end-to-end secure deployment workflow.

Hardening Your Self-Hosted Vaultwarden

You wouldn’t leave the front door of your house open just because the safe inside is locked. Same logic applies here. The vault is encrypted, but you still want to harden the perimeter.

• Disable open signups (SIGNUPS_ALLOWED=false) the moment your own account is created. Use INVITATIONS_ALLOWED=true for family/team onboarding instead.
• Set SHOW_PASSWORD_HINT=false: by default the server will tell anyone who asks “what was the hint for this email?” which is a free username-enumeration gift to attackers.
• Put it behind a WAF like our ModSecurity + OWASP CRS NGINX build (see our CRS install guide). Brute-force probes on /admin stop dead at the WAF.
• Enable fail2ban on the Vaultwarden log file. There are ready-made jail definitions in the Vaultwarden wiki.
• Pin a specific image tag rather than :latest in production, so you don’t get a surprise upgrade at 3 a.m.
• Backups, backups, backups. A nightly sqlite3 /data/db.sqlite3 ".backup /backups/$(date +%F).sqlite3" plus a copy of the attachments/, sends/, and rsa_key* files is the bare minimum. Off-site copy too. If you lose rsa_key.pem, every existing 2FA token breaks.
• Monitor it. Even a simple healthcheck ping against your domain catches outages before users do.

A generic CRS install stops the obvious noise, but Vaultwarden has a small, fully-known request surface, so we wrote a purpose-built OWASP CRS plugin for it: vaultwarden-crs-plugin. It does two things. First, it removes the false positives CRS would otherwise raise on legitimate traffic, the Argon2 admin token, the OAuth password-grant hashes on /identity/connect/token, and the end-to-end-encrypted EncString blobs that every cipher/account/send write carries. Second, it adds an opt-in positive-security layer: a path allowlist built straight from Vaultwarden’s own source (/api, /identity, /admin, /icons, /notifications, /attachments and the web-vault static tree), so scanner probes for /wp-login.php, /.env or /vendor are denied before they ever reach the backend. Because Vaultwarden is a JSON API, it deliberately ships no argument-name allowlist (those keys vary per client). It runs on vault.myguard.nl today. Drop the three plugins/*.conf files into your CRS plugins directory and enable it per-vhost, see the README for the full roll-out.

A Quick Tour of vault.myguard.nl

Want to see what a well-tuned Vaultwarden install actually looks like in the wild? Point your browser at vault.myguard.nl. It’s a real, production Vaultwarden instance running on the exact same Docker + NGINX + ModSecurity stack we ship as packages on this site. Open signups are disabled (sorry, invitation only), but you can see the login page, the TLS configuration, the response headers, and the overall snappiness. It’s a useful reference for what “done right” feels like.

The vault.myguard.nl instance is fronted by our extended Angie build with the OWASP CRS WAF, brotli + zstd compression (see our compression deep dive), HTTP/3, and a strict CSP. The container itself is a stock vaultwarden/server:latest with SQLite. Backups go to encrypted off-site storage every night. Total resource use: under 100 MB of RAM, less than 1% of one CPU core at idle. It’s almost embarrassing how little it costs to run.

Frequently Asked Questions

Is self-hosted Vaultwarden safe?

Yes, provided you keep it updated, run it behind HTTPS, and back it up. Your vault is encrypted on the client before it touches the server using your master password as the key. Even a full server compromise leaks ciphertext, not plaintext passwords. The risk profile is genuinely lower than most cloud password managers, because you’re not in a giant shared blast radius.

Can I use the official Bitwarden apps with Vaultwarden?

Absolutely, and you should. Vaultwarden implements the Bitwarden API, so every official client (browser, mobile, desktop, CLI) works perfectly. Just change the server URL in the client settings before logging in.

What happens if I forget my master password?

Your vault is gone. There is no recovery, no “forgot password” link, no admin override. That’s a feature, not a bug, the server literally cannot decrypt your data, so it can’t help you. Mitigation: write your master password on paper and store it in a safe, or set up Emergency Access with a trusted person, or print an encrypted recovery code. Do this before you forget.

SQLite or MySQL/PostgreSQL?

SQLite is the default and is genuinely fine up to a few hundred users. It’s fast, has zero moving parts, and backs up by copying one file. Only switch to MySQL or PostgreSQL if you have a clustered/HA setup or several thousand active users. Don’t over-engineer this.

How much will hosting cost me?

If you’ve already got a VPS or home server, effectively zero. From scratch, a €3–5/month VPS comfortably runs Vaultwarden for an entire family. The container needs about 50 MB of RAM and barely any CPU. A Raspberry Pi Zero 2 W can run it too, if you’re feeling sporty.

Does Vaultwarden support passkeys (WebAuthn)?

Yes. Recent versions support passkey storage in the vault and WebAuthn as a 2FA method for logging in to Vaultwarden itself. You can store passkeys for sites that support them and sync them across all your devices via your self-hosted vault, the same convenience Apple/Google offer, but on hardware you own.

Should I store TOTP codes in the same vault as my passwords?

It’s a trade-off. Storing them together is wildly more convenient and means losing your phone doesn’t lock you out of 50 accounts. The cost: if someone cracks your master password and bypasses your 2FA, they get everything. Mitigation: use a long, unique master passphrase, enable WebAuthn or a YubiKey as 2FA on the vault itself, and consider keeping a tiny separate authenticator app for your most critical accounts (bank, email, vault recovery).

Passkeys vs TOTP, which one should I use?

If a site offers passkeys, use them. They’re phishing-resistant by design (the browser checks the domain cryptographically), there’s no code to type or screenshot, and they’re faster. TOTP is the fallback when a site hasn’t added passkey support yet, which is still most of the internet. In practice you’ll use both for years. Vaultwarden handles both seamlessly.

Related Reading

• Vaultwarden on GitHub: official source code, releases, and issue tracker (dani-garcia/vaultwarden).
• Vaultwarden Wiki: the authoritative docs: every env var, reverse-proxy examples, backup & fail2ban guides.
• vaultwarden/server on Docker Hub: the official container image and tag list.
• WordPress NGINX Configuration: PHP-FPM, FastCGI Cache and Redis: the same NGINX patterns used to front Vaultwarden, applied to WordPress.
• How to Install ModSecurity and OWASP CRS on NGINX: add a real WAF in front of your Vaultwarden admin panel.
• WordPress Hardening Plugin for ModSecurity CRS: companion hardening for the WordPress side of your stack.
• Zstd vs Brotli vs zlib-ng: squeeze every kilobyte out of your Vaultwarden web vault responses.

More self-hosting builds on our Docker overview page.

Spoiler: it can. The BREACH attack is a compression side-channel attack against HTTPS responses. It does not snap TLS like a cartoon villain with bolt cutters. Instead, it abuses a quiet little detail, compressed responses get a tiny bit shorter when their contents repeat. If an attacker can sneak text into a request and then squint at how big the encrypted reply comes back, they can slowly, patiently, annoyingly recover hidden things like CSRF tokens, password reset codes, email addresses, or other values you genuinely did not want on the front page.

Yes, really. Your site can have a perfectly modern TLS setup, an A+ on every scanner, and still gently leak secrets because compression was trying to be helpful at exactly the wrong moment. I know. Rude.

What Is the BREACH Attack, in Plain English?

BREACH stands for Browser Reconnaissance and Exfiltration via Adaptive Compression of Hypertext. That name is doing the absolute most, so let us put it in human language.

Imagine you are packing for a trip and you have one of those vacuum bags that suck out all the air. Stuff two fluffy sweaters in there, and the bag shrinks more than it would with just one. Now imagine a nosy neighbour who is not allowed to look inside the bag, but they can pick it up and weigh it. They sneak in different items, weigh the bag each time, and the second one of their items matches something already inside, the bag gets noticeably lighter. Congratulations, neighbour. You just learned what is in someone else’s suitcase without ever opening it.

That is BREACH. The vacuum bag is the compressed HTTP response. The sweater already inside is the secret, like a CSRF token. The attacker’s test items are bits of text reflected into the page, a search query, an error message, a URL parameter, the kind of thing that bounces back into HTML without anyone thinking twice. All the attacker really needs is the ability to trigger lots of requests and watch how big the encrypted responses come back.

The key point, and please tattoo this on your brain, BREACH is not about breaking encryption directly. TLS can be flawless. The leak comes from the size of the response. Encryption hides the words. It does not hide the page count.

How Does a BREACH Attack Actually Work?

For the BREACH attack to succeed, four ingredients usually have to show up at the same party:

1. The victim is logged in, or the response carries a secret tied to that session.
2. The application reflects attacker-controlled input somewhere in that same response.
3. The response is compressed with gzip, Brotli, or similar content compression.
4. The attacker can fire off many requests and measure how big the replies come back.

When those four line up, you have the world’s most patient, most boring guessing game. Let’s walk through it.

Step 1: A secret is sitting inside the HTML

Picture a logged-in page with a sneaky little hidden form field:

<input type="hidden" name="csrf" value="r9Gk3LxV...">

That token is there for a great reason, it stops forged form submissions. The drama starts when the same page also reflects user input, for example:

<p>You searched for: BRE...</p>

If the attacker can choose the search term, they can keep tossing in guesses that might overlap with the secret token. Whenever the guess matches a chunk of the token, gzip and Brotli go “ooh, repetition, let’s save bytes!” and the response shrinks ever so slightly. That tiny shrink is the leak.

Step 2: The attacker keeps poking

The attacker drops the victim onto a malicious page somewhere else on the internet, maybe an ad, maybe a sketchy link, maybe a popup that absolutely no one asked for. That malicious page tells the victim’s browser to send lots of requests to the target site. The browser obediently attaches the victim’s cookies (because that is what browsers do), so the target site returns the real, logged-in page with the real secret tucked inside.

The attacker cannot read the response body because of the same-origin policy. Cool, but they don’t need to. They just need the size of each encrypted reply. Each guess that happens to share characters with the secret produces a slightly smaller payload, and the attacker takes note like a stalker with a kitchen scale.

Step 3: One byte at a time, like an exceptionally patient bird

By repeating this with thousands of slightly different guesses and comparing the sizes, the attacker can recover the secret one character at a time. It is slow, fiddly, and data-hungry. It is also extremely real. Side-channel attacks always sound silly until you remember they are basically statistics in a balaclava.

Step 4: The attacker uses the stolen secret

Once a CSRF token, reset code, or other session-bound secret has been recovered, the attacker can use it to bypass the very protection that secret was supposed to provide. Which, if we are being honest, is the genuinely insulting bit. You added a CSRF token for safety. Compression turned it into a hint system. Cool. Cool cool cool.

Why HTTPS Alone Does Not Save You

This is the part that feels deeply unfair, so let’s name it: HTTPS does its job. It protects the contents of your traffic in transit. It just does not hide the brute fact that one encrypted response is 12,438 bytes and the next one is 12,431 bytes.

BREACH lives in that seven-byte difference.

Think of it like this: someone outside your living room cannot hear the actual words of your conversation through the wall. But they can absolutely tell when the room goes dead silent, when everybody laughs at once, and when somebody drops a wine glass. Metadata leaks are still leaks. Compression side-channel leaks are metadata leaks with a postgraduate degree and a smug attitude.

This is also why “just turn off TLS” is not a fix. That is fixing a squeaky brake by setting the car on fire. Please do not.

BREACH vs CRIME vs HEIST: Same Family, Different Tricks

Security researchers love naming attacks like rejected metal bands, so here is the quick family tree:

CRIME targeted TLS or SPDY compression itself. It mostly went out of style once TLS-level compression was disabled almost everywhere.

BREACH targets HTTP response body compression. That is the one that still matters today, because gzip and Brotli are still happily compressing your responses for all the right performance reasons.

HEIST and related browser-side techniques showed that even without a network vantage point, an attacker can sometimes coax the browser into revealing timing or size details. Cute. Hate it.

The unifying lesson is simple: if secrets and attacker-controlled input share the same compressed output, somebody clever will turn that into an oracle. Treat that as a law of nature.

Why Padding Is Usually False Security

Padding sounds smart at first. “If response sizes leak information, just add some random bytes so the sizes become noisy. Done. Pub?” Sadly, no pub.

Padding is usually false security because it treats the symptom, not the cause. Let’s look at why.

Random noise gets averaged out

If an attacker can fire off thousands of requests, and they can, random padding turns into background fuzz. The attack signal does not vanish. It just needs more samples. Given enough tries, averages chew through the noise and the size differences become useful again. Statistics: still in the balaclava.

Fixed padding is essentially decoration

If you always add the exact same amount of padding, you have done… almost nothing. Every response is still comparable to every other response. You have just made the whole site slightly bigger, which is an expensive way to feel safe.

Developers wildly overestimate it

This is the genuinely dangerous bit. Once padding is enabled, teams move on with confidence. “Yep, BREACH? Handled.” Meanwhile the actual vulnerability sits there untouched, because a secret and attacker-controlled reflection are still cohabiting in the same compressed response.

Padding rarely lands exactly where it matters

For padding to be useful, it must be unpredictable, carefully sized, applied consistently, and hard for an attacker to model. In real life? One template adds it. Another forgets. One response path pads before compression. Another pads after. Suddenly your safety blanket has holes, the holes are also on fire, and somebody is filming it for TikTok.

Padding can make exploitation a bit harder. That is fine as a secondary friction control. It is not a trustworthy primary defense against the BREACH attack.

What Can a BREACH Attack Actually Leak?

The poster child is the CSRF token because it loves to live directly in HTML forms. But BREACH is not married to CSRF. Any secret that ends up in a compressible response can become a target, such as:

• CSRF tokens
• Password reset tokens
• Email addresses or partial personal info
• Session-bound anti-abuse tokens
• OAuth state values or one-time nonces
• API keys or internal identifiers accidentally rendered into templates

If it is secret, stable enough to guess incrementally, and shares a compressed response with attacker-controlled input, it earns a spot on your threat model. No exceptions, sorry.

How to Prevent the BREACH Attack Properly

Okay. Enough admiring the problem. Adult mode now.

1. Disable compression on sensitive dynamic responses

The most direct mitigation is to turn off gzip and Brotli for the responses that contain secrets and reflect input. Think login forms, account pages, authenticated search, password reset flows, settings forms, and admin panels. Basically anywhere your site whispers secret things to a logged-in user.

For NGINX or Angie, be surgical instead of nuking from orbit. You do not need to disable compression for the entire site. Static assets and public pages can stay compressed. The sensitive authenticated HTML is where you want to be cautious.

location /account/ {
    gzip off;
    brotli off;
}

location /wp-admin/ {
    gzip off;
    brotli off;
}

If you are already tuning compression on NGINX or Angie, the broader context lives in our comparison of Brotli, zstd, and zlib-ng compression.

2. Stop reflecting attacker-controlled input next to secrets

This is honestly one of the best fixes, because it kills the oracle dead. If a page contains a CSRF token, it should not also be echoing user-controlled query parameters, search terms, or any other reflected data straight into the same compressed template, at least not unless you really have to.

Separate those concerns. Move the search UI onto a different response. Push live reflection out to a public endpoint that doesn’t carry session secrets. Rewrite templates so secrets are not nestling up against attacker-controlled bytes like they’re on a first date. Less glamorous than buying a shiny new WAF module, but often dramatically more effective.

3. Use CSRF defenses that do not create a stable compression target

Yes, you still need CSRF protection. No, plain old static tokens stamped into every compressed page are not enough on their own.

Safer patterns include:

• Per-request or masked CSRF tokens: the exposed value changes every time, so a recovered value is useless about three milliseconds later.
• Synchronizer tokens combined with careful placement, so they are not sharing a compressed response with attacker input.
• Double-submit cookie patterns where appropriate, with strong cookie flags and proper validation.

The goal is not “remove CSRF protection.” The goal is “do not let your CSRF token act as a reusable compression oracle.”

4. Enforce SameSite cookies

Cookies tagged with SameSite=Lax or SameSite=Strict can reduce the browser’s willingness to send authenticated cookies on cross-site requests. That matters, because BREACH usually relies on the victim’s browser cheerfully sending credentialed requests from an attacker-controlled page.

This is not a complete BREACH attack fix on its own, but it shrinks the attack surface in a real way, and it helps with garden-variety CSRF too. One of those rare security knobs that is both boring and useful, which honestly is the dream.

5. Validate Origin and Referer headers

For state-changing requests, validate the Origin header where you can, and fall back to Referer checks where it makes sense. Not perfect, not magical, but it raises the bar for cross-site abuse and pairs nicely with token-based defenses.

If your app accepts dangerous actions purely because one hidden field happened to match, you are trusting one layer to do everything. BREACH absolutely loves a single layer.

6. Rate-limit suspicious repeated requests

BREACH needs a lot of measurements. That makes rate limiting, anomaly detection, and bot friction genuinely useful as supporting controls. If one page is getting hit by thousands of tiny variant requests in a tight window, that is something your stack should notice and react to, not shrug at.

On the web-server side, you can pair app logic with controls like ModSecurity or request throttling. If you are already hardening a WordPress or NGINX stack, our ModSecurity and OWASP CRS guide and our WordPress hardening write-up cover broader request-filtering patterns that help here too.

7. Keep secrets out of compressible HTML when you can

If a secret does not need to be in the page, do not put it there. Move it server-side. Use headers or dedicated non-compressed endpoints where it fits. Ask whether the template genuinely needs to render that value at all, a shocking amount of “required” template data turns out to be legacy furniture nobody has questioned since 2019.

8. Segment public and authenticated experiences

Public pages can be aggressively cached and compressed. Authenticated pages deserve stricter handling. If you serve WordPress through NGINX or Angie, this split is already a good idea for both performance and security. The same architecture that gives you a great cache hit rate also makes it much easier to disable compression precisely where secrets live.

The broader setup work is covered in our WordPress on NGINX and PHP-FPM guide and in our reverse proxy configuration article.

What Not to Do

• Do not assume HTTPS by itself solves the BREACH attack. It does not.
• Do not keep secrets and attacker reflection in the same compressed response just because “the page works fine.”
• Do not rely on random padding as your main mitigation. It is a friction control at best.
• Do not nuke compression across your whole site unless you genuinely have no better option. Be selective and deliberate.
• Do not treat CSRF tokens as magical objects. They are only as strong as the design around them.

A Practical BREACH Defense Checklist

1. Inventory pages that contain secrets and user-controlled reflection.
2. Disable gzip and Brotli on those sensitive responses.
3. Mask or rotate CSRF tokens so they are not stable reusable targets.
4. Enable SameSite, Secure, and HttpOnly on cookies.
5. Validate Origin and, where appropriate, Referer on state-changing requests.
6. Rate-limit repeated probing patterns and watch for anomalies.
7. Keep public compressed content separated from authenticated secret-bearing content.
8. Audit templates for needless reflection of attacker-controlled input.

That list is dramatically less sexy than saying “we added padding.” It is also dramatically more likely to actually protect you. Mood.

Why the BREACH Attack Still Matters in 2026

Because performance tuning and security tuning keep slamming into each other in the same hallway, and neither is willing to apologise.

Everyone wants smaller responses, faster pages, lower bandwidth bills, and greener hosting. That is why compression is everywhere. Modern stacks also keep pushing more state, more personalization, and more tokens into dynamic HTML. That is why compression side channels keep finding fresh rooms to lurk in.

BREACH is not the only compression-based leak on the planet, but it remains the perfect reminder that a feature can be correct, useful, and dangerous all at the same time, depending on what you wrap around it. Compression itself is not the villain. Mixing secrets and attacker-controlled input into one compressed response is the villain. Blame the packing choices, not the vacuum bag.

Frequently Asked Questions

What is the BREACH attack in one sentence?

The BREACH attack is a compression side-channel attack that uses tiny differences in compressed HTTPS response sizes to help an attacker guess secrets such as CSRF tokens or password reset tokens, one character at a time.

Does BREACH mean I should disable gzip or Brotli everywhere?

No, and please don’t. The practical fix is to disable compression selectively on sensitive dynamic pages that contain secrets and attacker-controlled reflection. Public assets and ordinary static content can stay compressed.

Why are CSRF tokens involved so often?

Because CSRF tokens are usually baked directly into HTML forms and stay stable long enough to be guessed in pieces. If they show up in a compressed response alongside attacker-controlled input, they become a perfect BREACH attack target.

Is random padding a good BREACH mitigation?

Only as a minor supporting friction control. Padding adds noise, but attackers can usually average that noise out with enough samples. Do not let it be your main defense.

Can SameSite cookies help prevent BREACH?

They reduce the browser’s willingness to send authenticated cookies on cross-site requests, which makes BREACH-style probing harder. Useful and very welcome, but not a full replacement for careful compression and template design.

Is BREACH only a WordPress problem?

Not at all. Any web application can be vulnerable if it compresses responses that contain secrets and attacker-controlled reflection. WordPress, custom PHP apps, Python frameworks, Node.js apps, Java stacks, all can fall into the same trap.

How long does a BREACH attack actually take?

It depends on how stable the secret is, how cleanly attacker input is reflected, and how aggressively the attacker can issue requests. In friendly conditions a token can be recovered in minutes to hours; in less friendly conditions it may not be practical at all. Either way, “not always fast” is a poor reason to leave the door open.

Related Posts

• How to Install ModSecurity and OWASP CRS on NGINX: A practical guide to adding request filtering and defensive friction at the web-server layer.
• WordPress Hardening Plugin for ModSecurity CRS: A broader hardening strategy for blocking abusive traffic before it ever reaches your PHP code.
• NGINX zstd vs Brotli vs zlib-ng Compression: Useful background if you are tuning compression and want to understand what to disable where.
• WordPress NGINX Configuration: PHP-FPM Tuning, FastCGI Cache and Redis: Covers the architectural split between public cached traffic and authenticated dynamic traffic.

Zstd, short for Zstandard, is a lossless compression format designed by Yann Collet and open-sourced by Facebook in 2016. In plain English: it squishes files and HTTP responses so they travel faster, but the browser gets the exact original content back on the other side. No mystery meat, no quality loss, no weird “your CSS came back as soup” situation.

The reason people suddenly care is simple: Zstd tries to hit a very attractive middle ground. Gzip is old, dependable, and everywhere. Brotli often wins on compression ratio, especially for static assets, but it can ask for more CPU patience. Zstd aims for a sweet spot where compression is strong, decompression is very fast, and the tuning range is broad enough that you can bias for speed or ratio depending on your traffic. For web servers, that is a nice sentence to hear right before the graphs stop looking sad.

If you already read our zstd vs Brotli vs zlib-ng comparison for NGINX, this article is the prequel. This one answers the beginner questions: what Zstd actually is, why it exists, how it got here, which browsers support it, and how we use it in our NGINX builds and our Angie builds.

What is Zstd, exactly?

Think of web compression like packing a suitcase. Gzip is the sturdy old suitcase your parents used for twenty years. Brotli is the fancy vacuum bag that can squeeze a shocking amount into a tiny space, but sometimes makes packing slower. Zstd is the smart carry-on with wheels, a charger, and just enough room to keep airport drama to a minimum.

Technically, Zstd is a modern lossless compression algorithm standardized in RFC 8878. It is designed to offer a wide speed-versus-ratio range, fast decompression, and optional dictionary compression for repeating small payloads. Outside the web, that made it popular in places like Linux packaging, filesystems, databases, and backup tools long before browsers started speaking zstd in HTTP.

That “lossless” part matters. When a browser receives Content-Encoding: zstd, it decompresses the body back to the original HTML, CSS, JavaScript, JSON, or SVG byte stream. Nothing is thrown away. The whole trick is just moving fewer bytes across the wire.

Why does Zstd exist?

Because the internet is rude. Pages got bigger, APIs got chattier, CPUs got faster, and nobody wanted to choose between “tiny responses” and “reasonable server load” forever. Zstd was created to improve on the trade-off that older formats left on the table.

The official project describes Zstd as a fast compression algorithm with high compression ratios and an extremely fast decoder. That decoder speed is a big deal for the web. Compression happens on your server, but decompression happens on every client device. If decompression is lightweight, the format becomes much more practical for browsers and mobile devices.

That is also why Zstd spread beyond websites. Package managers adopted it because installs and updates benefit from fast decompression. Filesystems liked it because “smaller on disk but still quick to read” is basically catnip for infrastructure engineers. Once browsers added support for HTTP Content-Encoding: zstd, the web finally had a reason to bring that momentum into day-to-day page delivery.

A short, useful history of Zstd

Zstd was initially released in 2015, then open-sourced publicly in 2016. The format later landed in the IETF standards process, which is why it now has a proper RFC instead of just “trust us, this GitHub repo looks serious.” Over the following years, it spread through Linux and infrastructure tooling: kernels, package formats, storage layers, databases, and archive utilities all started adopting it.

The web side moved more slowly. For a while, Zstd was the compression nerd’s favorite party trick: powerful, promising, but not broadly useful for public sites because browsers were not asking for it yet. That changed in 2024 when Chromium-based browsers began supporting Zstd content encoding, followed by Firefox. Safari support arrived later and more awkwardly, which is about as surprising as rain being wet.

By 2026, the picture is much better. The current browser landscape is finally good enough that Zstd has moved from “interesting lab experiment” to “real production option,” especially when used as an addition to gzip and Brotli rather than a reckless replacement for everything.

Which browsers support Zstd?

Modern browser support is now real, not imaginary marketing support. Based on current MDN and Can I Use data, Zstd content encoding is supported in Chrome and Edge from version 123, Firefox from version 126, and Opera from version 109. Safari and Safari on iOS joined later, with newer-version caveats. In other words: the big modern engines are catching up, but Apple took the scenic route.

The important production takeaway is not “great, delete gzip.” The real takeaway is: keep sane fallbacks. Clients advertise what they support with the Accept-Encoding request header. Today, common modern browser requests can include gzip, deflate, br, zstd. Your server should negotiate the best option the client actually supports and keep older or partial-support clients on gzip or Brotli where needed.

Which web servers support Zstd?

This is where things get gloriously uneven.

Caddy has first-class Zstd support in its encode directive. In fact, Caddy documents zstd and gzip as the default enabled formats if you use encode with no arguments. That is a clean, built-in experience.

Stock NGINX, on the other hand, still documents gzip and gzip_static as its standard compression path. If you want Zstd in NGINX, you need a third-party module. That is exactly why our builds package the hardened http-zstd module. The same story applies to Angie in our repository: Zstd support comes from the module, not from a magical checkbox hidden in the attic.

Apache httpd remains much more old-school here. Its official mod_deflate documentation still centers on gzip-compatible DEFLATE output. So if your question is “does every major web server do native Zstd out of the box now?”, the answer is no. The ecosystem is moving, but it is not uniform yet.

How we use Zstd in NGINX and Angie

The module in modules/nginx/http-zstd ships two practical pieces: a filter module for dynamic compression and a static module for serving pre-compressed .zst files. The README’s recommended baseline is refreshingly boring, which is good. Boring config is how production stays married.

http {
    zstd             on;
    zstd_comp_level  3;
    zstd_min_length  1000;
    zstd_types       text/plain text/css application/json
                     application/javascript text/xml application/xml
                     application/xml+rss text/javascript image/svg+xml;

    gzip_vary        on;

    server {
        location /api/ {
            proxy_pass http://backend;
        }

        location /static/ {
            zstd_static on;
            root /var/www;
        }
    }
}

Here is what matters:

• zstd on; enables dynamic compression for matching responses.
• zstd_comp_level 3; is the module’s documented all-around default and a sensible starting point.
• zstd_min_length 1000; avoids wasting CPU on tiny responses that often get bigger when compressed.
• zstd_types controls which MIME types are eligible. Text, JSON, JS, XML, and SVG are the obvious wins.
• gzip_vary on; is important even with Zstd, because you still need Vary: Accept-Encoding so proxies and caches do not hand the wrong compressed variant to the wrong client.
• zstd_static on; tells the static module to serve pre-compressed .zst files when the client accepts them.

The module also documents extra controls like zstd_max_length, zstd_buffers, zstd_target_cblock_size, and zstd_dict_file. The last one comes with a very important warning: dictionary compression is not generally safe for public web traffic unless you fully control both ends, because plain HTTP content negotiation does not magically tell the client which dictionary was used. Translation: dictionary compression is cool, but do not sprinkle it on your public site like parmesan.

If you want the module in ready-to-use packages instead of compiling your weekend into dust, our NGINX modules builds and Angie modules builds package that work for you. For the broader tuning story around TLS, HTTP/3, caching, and modules, our expert NGINX and Angie guide picks up where this article stops.

Is Zstd production-ready?

Yes, with one adult-sized caveat: use it like an addition to your compression strategy, not a religion.

The format itself is mature. The library is widely used. The browser support story is now good enough to matter. Our hardened NGINX module fork is explicitly production-oriented, with regression tests, ASAN and UBSAN coverage, continuous fuzzing of the Accept-Encoding parser, and ongoing CI. That is not “some guy pushed a tarball in 2019 and vanished into the hills.”

What is not mature yet is universal deployment symmetry. Not every browser version supports Zstd. Not every web server ships it natively. Not every CDN or proxy path will behave the way you hope if you make reckless assumptions. So the safe production pattern is:

• Keep gzip as the universal fallback.
• Use Brotli where it already makes sense for static assets.
• Add Zstd for modern clients that advertise support.
• Use Vary: Accept-Encoding correctly.
• Measure real CPU, latency, and cache behavior instead of composing fan fiction from benchmark charts.

That is the boring answer. It is also the answer that does not wake you up at 3 a.m.

Frequently Asked Questions

Is Zstd better than gzip?

Often, yes, especially when you care about fast decompression and a strong speed-to-ratio balance. But “better” depends on your clients, traffic shape, and how much CPU you want to spend. Gzip is still the universal fallback because everybody understands it.

Is Zstd better than Brotli?

Not in a simple winner-takes-all way. Brotli can still be excellent for static assets when you want maximum squeeze. Zstd is attractive because it is very fast, flexible, and increasingly supported, especially for dynamic content and broader infrastructure use.

Does stock NGINX support Zstd by default?

No. Stock NGINX documentation still focuses on gzip and gzip_static. To serve Content-Encoding: zstd with NGINX, you need a module such as the hardened http-zstd module we package.

Can I use Zstd on a public website right now?

Yes, but do it sensibly. Offer Zstd only to clients that actually advertise support, and keep gzip or Brotli as fallbacks. Production is about graceful negotiation, not emotional commitment.

Should I use dictionary compression for website responses?

Usually no, not for normal public traffic. The module documentation warns that HTTP does not include built-in dictionary discovery for regular Content-Encoding: zstd responses, so dictionary use is mainly for controlled environments where you manage both ends.

Is Zstd only for websites?

No. That is part of why it is interesting. Zstd is heavily used in packaging, filesystems, databases, backups, archives, and other infrastructure tooling. The web is joining a party that Linux and backend systems started years ago.

Related Posts

• zstd vs Brotli vs zlib-ng: The NGINX Compression Showdown: if you want a side-by-side compression strategy decision instead of the history lesson.
• NGINX Modules optimized & extended: the package page for our NGINX builds with the extra module set.
• Angie modules optimized & extended: the Angie counterpart if you prefer the NGINX fork with extra features and a friendlier pace.
• Nginx & Angie: The Expert Guide to Maximum Performance and Security: the bigger tuning guide for people who came for compression and stayed for the whole server stack.

Zstd is not magic. It is just a very good tool that finally arrived where normal web admins can use it without feeling like they joined a secret compression cult. That alone makes it worth paying attention to.

See also: HTTP/3 and QUIC on NGINX: Setup and Tuning (2026).

What Is a WordPress Database (And Why Should You Care)?

Let’s start from absolute zero, because nobody’s born knowing this. Every WordPress site has two halves. The first is the files, your theme, your images, your plugins. The second is the database: a big, organised filing cabinet that stores all your actual content. Every post, every page, every comment, every setting, every “remember this user is logged in” note, it all lives in the database, specifically a system called MySQL (or its near-identical twin, MariaDB).

Here’s the problem. That filing cabinet never cleans itself. WordPress and your plugins are constantly opening drawers, shoving paper in, half-deleting things, and leaving sticky notes everywhere. Over time the drawers get jammed, the folders get fat, and finding anything takes longer. In database terms, that’s fragmentation, bloat, and missing indexes, and the symptom you actually notice is a slow website. Pages crawl. The admin dashboard lags. Visitors bounce. Google notices. You lose money. Yes, really.

This is exactly the gap Database Boost fills. It’s a free WordPress database optimization plugin that does the cleaning, repairing, optimizing, indexing, and maintenance for you, and crucially, it tells you what it’s doing and why, like a friendly mechanic who actually shows you the worn-out part instead of just handing you a bill.

Why Use Database Boost? The Honest Pitch

There are other database plugins. Some are great. So why this one? Because most of them treat you like you already have a computer science degree, or they hide a “one-click optimize” button that does mysterious things you can’t see or undo. Database Boost was built on a different idea: a non-technical person should be able to use it safely and understand it. Here’s what makes it worth installing.

It explains everything like you’re smart but new

Every screen has plain-language descriptions. “This table is 40% wasted space” instead of “fragmentation ratio 0.40.” A built-in Docs tab walks you through each feature in a warm, mentor-y tone. You’re never left guessing what a button does before you press it.

It’s careful before it’s powerful

Database operations can be destructive, deleting the wrong thing is bad. Database Boost is paranoid on your behalf. It warns you before risky operations, nudges you to back up first, and as of version 1.0.6 it checks every table name against a strict safety rule and a live database allowlist before it ever runs a delete. The database importer makes you type an explicit confirmation and honestly tells you that some operations can’t be fully undone. That honesty is rare, and it’s the whole point.

It’s free, and it doesn’t nag you to upgrade

No locked features behind a “Pro” paywall on the stuff that matters. The full database management suite, repair, optimize, indexes, diagnostics, cleanup, slow query monitoring, is all included.

What Database Boost Actually Does, Feature by Feature

Let’s open every drawer. Here’s the full toolkit, in human terms.

• Table Repair: Databases can get corrupted, like a scratched DVD. This finds damaged tables and fixes them before they take your whole site down.
• Table Optimization: Remember the jammed filing cabinet? This is the equivalent of taking everything out, throwing away the empty folders, and packing it back tight. Reclaims wasted space, speeds up queries.
• Index Management: An index is like the tab dividers in that filing cabinet. Without them, the database reads every single page to find one thing. Database Boost spots missing indexes and adds them with one click. This is often the single biggest speed win.
• Health Diagnostics: A real-time check-up of your MySQL/MariaDB configuration and table health, with RAM-aware advice (it actually looks at your server’s memory before telling you what to change).
• Slow Query Monitor: Logs the database requests that are dragging their feet, so you can see exactly what’s making your site slow instead of guessing.
• Cleanup Tool: Detects and removes debris from plugins you uninstalled long ago. It knows the leftover patterns of hundreds of common plugins.
• Maintenance Mode: Politely puts up a “back in a minute” sign during big operations, while keeping admin, login, cron and REST reachable so you don’t lock yourself out.
• Automated Scheduling: Set it and forget it. Daily health checks via WordPress cron, with optional auto-repair, auto-optimize and auto-index.
• Post-Update Safety: After a WordPress core update, it can automatically re-check indexes and run a conservative cleanup.
• WooCommerce Support: Runs an online shop? It includes all WooCommerce order and product tables in every operation.
• WP-CLI Commands: For the command-line crowd: wp mysql repair|optimize|indexes|diagnostics|cleanup.
• Site Health Integration: Your database status shows up right inside WordPress’s built-in Site Health screen.

How to Get Started (No Terminal Required)

Here’s the beautiful part: you don’t need to touch a command line, ever. Install and activate the plugin, and you’ll find a new Database Boost menu in your WordPress admin sidebar. The honest, friendly first move is this:

1. Back up your site first. Always. Database Boost will remind you, but do it anyway. A backup is a parachute: you hope you never need it, but you do not jump without one.
2. Open the Diagnostics tab and run a Health Check. This is read-only: it looks but doesn’t touch. It’ll show you fragmented tables, missing indexes, and config advice.
3. Run Optimize and Add Indexes from the action panel. Watch the inline results appear right below the buttons. This is where most sites get a noticeable, immediate speed bump.
4. Try the Cleanup tab to clear out old plugin debris and expired transients. It shows you what it found before it removes anything.
5. Optionally enable scheduling in Settings so it quietly maintains itself from now on.

Is It Safe? Let’s Be Honest About the Risks

I’m not going to tell you database tools are risk-free, because that would be a lie and you deserve better. Repairing, optimizing and cleaning a database are powerful operations. Done carelessly, you can lose data. That’s true of every database plugin, not just this one.

What makes Database Boost trustworthy is that it treats that risk with respect instead of hiding it. It runs automated maintenance in a conservative mode, skips operations if another one is already running, batches heavy work so it doesn’t hammer your server, and flatly tells you when something can’t be rolled back. Pair it with a backup and a little common sense, don’t run a giant cleanup five minutes before a product launch, and it’s genuinely safe for non-technical users. If you also care about keeping attackers out of that database in the first place, our WordPress hardening plugin for ModSecurity CRS is a great companion.

Frequently Asked Questions

Will Database Boost speed up my WordPress site?

Usually, yes, especially if your database has never been optimized or is missing indexes. The biggest gains come from adding missing indexes and reclaiming fragmented space. It’s not magic (a slow theme is still a slow theme), but for a bloated database it can be a dramatic, free improvement. For full-stack speed, also see our WordPress NGINX, PHP-FPM and Redis configuration guide.

Do I need to know SQL or use the command line?

No. Everything works through point-and-click screens in the WordPress admin. The WP-CLI commands exist for power users who want them, but they’re entirely optional. If you’ve never opened a terminal in your life, you’ll be completely fine.

Could it break my site or delete my content?

Optimize and repair are very safe. Cleanup and import are more powerful, which is why the plugin warns you, asks for explicit confirmation on destructive actions, and recommends a backup first. Always take a backup before a big cleanup, then you’re protected no matter what.

Does it work with WooCommerce?

Yes. WooCommerce stores a lot in the database (orders, products, sessions), so shops bloat fast. Database Boost automatically includes all WooCommerce tables in repair, optimize, indexing and diagnostics.

How often should I run it?

For most sites, a monthly optimize is plenty. Busy sites or big shops benefit from the built-in daily scheduled health check with auto-optimize enabled. Set it once in Settings and let it maintain itself.

Is Database Boost really free?

Yes, the full feature set is free. If it saves your weekend, there’s a Donate link in the plugin, entirely optional, much appreciated, never required.

The Bottom Line

Your WordPress database is the engine room of your whole site, and almost nobody maintains it until it’s already screaming. Database Boost makes that maintenance approachable, safe, and, dare I say, kind of pleasant, because it actually explains itself instead of talking down to you. Clean it, repair it, optimize it, index it, and let it look after itself. Your visitors (and your Google rankings) will quietly thank you.

Related Reading

• WordPress NGINX Configuration: PHP-FPM Tuning, FastCGI Cache and Redis: Speed up the rest of your stack once your database is lean.
• WordPress Hardening Plugin for ModSecurity CRS: Keep attackers away from that freshly-optimized database.
• zstd vs Brotli vs zlib-ng: The NGINX Compression Showdown: Shrink what you send to make pages load even faster.
• NGINX Rate Limiting: Protect Your Server from Bots and Brute Force: Stop bots from hammering your database with junk requests.

That bouncer is a Web Application Firewall (WAF), and in the open-source world the gold-standard combo is ModSecurity (the bouncer) plus the OWASP Core Rule Set (the bouncer’s encyclopaedic memory of every known troublemaker). This guide walks you through how to install ModSecurity and the OWASP CRS on NGINX, step by step, from absolutely zero. No prior WAF experience needed. If you can copy and paste into a terminal and not panic when text scrolls past, you can do this.

What is ModSecurity, and what is the OWASP CRS?

Let’s get the vocabulary sorted, because these two things get confused constantly and they are not the same.

ModSecurity is the engine. It’s a piece of software that plugs into your web server (NGINX, Apache, or via the modern Coraza/libmodsecurity builds) and inspects every single HTTP request before your application ever sees it. By itself, ModSecurity is a bouncer with no memory, it can stop people, but it doesn’t know who to stop. It needs rules.

The OWASP Core Rule Set (CRS) is that memory. It’s a free, community-maintained, battle-tested collection of detection rules, thousands of them, covering SQL injection, cross-site scripting (XSS), path traversal, remote code execution, protocol abuse, and basically every entry in the OWASP Top 10. The OWASP Foundation maintains it, real security professionals contribute to it, and it’s the de-facto standard ruleset for ModSecurity worldwide.

Put simply: ModSecurity is the muscle, the CRS is the brain. You need both. Installing one without the other is like hiring a bouncer and never telling him who’s banned.

Before you learn how to install ModSecurity NGINX: what you need

• A server running Debian or Ubuntu with NGINX installed (this guide assumes Debian/Ubuntu paths).
• Root or sudo access. You’ll be editing system config and reloading NGINX.
• An NGINX build with the ModSecurity module. This is the part most tutorials hand-wave. Stock distro NGINX does not include ModSecurity: you’d normally have to compile NGINX from source with --add-module, which is a multi-hour adventure in dependency pain. Our optimized NGINX builds for Debian and Ubuntu ship the http-modsecurity module precompiled, so this becomes a one-line apt install. We’ll assume that route.
• About 20 minutes and a cup of something warm.

Step 1, how to install ModSecurity NGINX module

If you’re using our repository, the ModSecurity-enabled NGINX and the dynamic module come straight from apt:

# Install NGINX and the ModSecurity dynamic module
sudo apt update
sudo apt install nginx nginx-module-modsecurity

# Verify the module file exists
ls -l /usr/lib/nginx/modules/ | grep modsecurity

You should see something like ngx_http_modsecurity_module.so. That .so file is the bridge between NGINX and the ModSecurity engine. If you compiled NGINX yourself instead, the module lives wherever your --modules-path pointed, adjust accordingly.

Step 2, Load the ModSecurity Module in NGINX

NGINX won’t use the module until you tell it to. Open your main config (/etc/nginx/nginx.conf) and add this line at the very top, before the events {} block, load_module directives have to come first:

load_module modules/ngx_http_modsecurity_module.so;

Then, inside the http {} block, switch ModSecurity on and point it at a rules file we’ll create in a moment:

http {
    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec/main.conf;

    # ... your existing http config ...
}

modsecurity on; arms the engine globally. modsecurity_rules_file tells it which rulebook to read. You can also place modsecurity on; inside a specific server {} or location {} block if you only want to protect part of your site, but for a WordPress site, protecting everything is the right call.

Step 3, Install the ModSecurity Base Configuration

ModSecurity ships a recommended baseline config. We’ll set up a clean directory and wire it together:

# Create the ModSecurity config directory
sudo mkdir -p /etc/nginx/modsec

# Grab the recommended base config
sudo wget -O /etc/nginx/modsec/modsecurity.conf 
  https://raw.githubusercontent.com/owasp-modsecurity/ModSecurity/v3/master/modsecurity.conf-recommended

# Grab the unicode mapping file it references
sudo wget -O /etc/nginx/modsec/unicode.mapping 
  https://raw.githubusercontent.com/owasp-modsecurity/ModSecurity/v3/master/unicode.mapping

The single most important setting in that base file is the engine mode. Open /etc/nginx/modsec/modsecurity.conf and find this line:

SecRuleEngine DetectionOnly

Leave it as DetectionOnly for now. This is the golden rule of WAF deployment that everyone ignores and then regrets. In DetectionOnly mode, ModSecurity watches everything and logs what it would have blocked, but doesn’t actually block anything. This lets you discover false positives (legitimate traffic the rules mistakenly flag) before they take your site down. We’ll flip it to full blocking in Step 6, after we’ve checked the logs. Patience now saves a 3 a.m. outage later.

Step 4, Install the OWASP Core Rule Set

Now the brain. We’ll pull the latest CRS 4.x release and put it where ModSecurity can find it:

# Clone the OWASP CRS (v4 branch)
cd /etc/nginx/modsec
sudo git clone https://github.com/coreruleset/coreruleset.git owasp-crs

# Activate the CRS setup file (it ships as .example so you can customise safely)
sudo cp owasp-crs/crs-setup.conf.example owasp-crs/crs-setup.conf

The crs-setup.conf file is where you tune the CRS’s behaviour, most importantly the Paranoia Level. Quick explainer: paranoia level is a dial from 1 to 4 that controls how suspicious the rules are. PL1 (the default) catches obvious attacks with very few false positives, the right starting point for almost everyone. PL4 catches everything including its own shadow and will absolutely flag legitimate traffic. Start at PL1. You can raise it later once you understand your traffic.

Step 5, Wire It All Together

Remember modsecurity_rules_file /etc/nginx/modsec/main.conf; from Step 2? We need to create that main.conf. It’s the master include file that loads everything in the correct order, base config first, then CRS setup, then the CRS rules themselves:

sudo tee /etc/nginx/modsec/main.conf > /dev/null <<'EOF'
# 1. ModSecurity base configuration
Include /etc/nginx/modsec/modsecurity.conf

# 2. OWASP CRS setup (paranoia level, anomaly thresholds, etc.)
Include /etc/nginx/modsec/owasp-crs/crs-setup.conf

# 3. The actual OWASP CRS detection rules
Include /etc/nginx/modsec/owasp-crs/rules/*.conf
EOF

Order matters here. The base config sets the engine behaviour, crs-setup.conf configures the ruleset, and the rules/*.conf glob pulls in every detection rule. Get the order wrong and rules reference variables that don’t exist yet.

Now test the NGINX config and reload:

sudo nginx -t
sudo systemctl reload nginx

If nginx -t says syntax is ok and test is successful, congratulations, ModSecurity and the OWASP CRS are now running on your server in detection mode. The bouncer is at the door, watching, taking notes, not yet throwing anyone out.

Step 6, Watch the Logs, Then Go Live

This is the step that separates people whose sites stay online from people who tweet “why is my site down” at midnight. Let detection mode run for a few days under real traffic. Then read the audit log to see what the CRS flagged:

# The audit log location is set in modsecurity.conf (SecAuditLog)
sudo tail -f /var/log/modsec_audit.log

You’re hunting for false positives, legitimate things on your site (a plugin’s AJAX call, a form with rich text, an admin action) that the rules flagged as attacks. For each one, you write a targeted exclusion rule so that specific legitimate request is allowed, without weakening protection everywhere else. For WordPress specifically, this is largely a solved problem, see the next section.

Once the logs are clean (or you’ve excluded the known false positives), flip the switch. Edit /etc/nginx/modsec/modsecurity.conf:

# Change this:
SecRuleEngine DetectionOnly
# To this:
SecRuleEngine On

sudo nginx -t && sudo systemctl reload nginx

The bouncer is now active. Attacks get blocked before they reach PHP, MySQL, or WordPress. You did it.

WordPress-Specific Tuning: Don’t Skip This

The stock CRS is a generalist, it protects a banking app and a recipe blog with the same rules. WordPress has very specific quirks (the Gutenberg editor sends complex POST bodies that can trip XSS rules; the REST API has its own patterns). Running raw CRS against WordPress without tuning will produce false positives in the admin area.

Two free CRS plugins solve this, and you should install both:

• wordpress-rule-exclusions-plugin: official CRS plugin that suppresses the known WordPress false positives (Gutenberg, the customizer, etc.) so the admin area works normally.
• wordpress-hardening-plugin: adds 25+ extra WordPress-specific protections on top of CRS: blocking xmlrpc.php, stopping user enumeration, rate-limiting wp-login.php brute force, GeoIP login restrictions, and IP reputation blocking. We wrote a full deep-dive on it, it turns generic CRS into a WordPress-aware fortress.

Both follow the CRS 4.0 plugin standard, drop them in the owasp-crs/plugins/ directory and they load automatically. Exclusions plugin first (removes false positives), hardening plugin second (adds protection). Together they give you a WAF that actually understands WordPress.

Related Reading

• Coraza WAF on NGINX: The Go-Powered ModSecurity Replacement: Prefer a memory-safe engine? Coraza runs this exact OWASP CRS setup on a Go rewrite of ModSecurity, with no C++ in the request path.
• WordPress Hardening Plugin for ModSecurity CRS: Block Attacks Without Touching Your PHP: The deep dive on the companion hardening plugin: all 25+ rules, rate limiting, GeoIP and IP reputation explained.
• NGINX Mainline: Optimized and Extended with 50+ Modules, Our NGINX builds ship the http-modsecurity module precompiled, so Step 1 is a one-line apt install instead of a from-source build.
• NGINX Rate Limiting: Protect Your Server from Bots, Scrapers and Brute Force: Pair native NGINX rate limiting with your new WAF for defence in depth.
• zstd vs Brotli vs zlib-ng: The NGINX Compression Showdown: Now your site is secure, make it fast too with modern compression.

FAQ

Does ModSecurity slow down NGINX?

There’s a small per-request CPU cost for rule inspection, typically a few milliseconds at Paranoia Level 1. For most sites this is completely unnoticeable and is massively outweighed by the benefit: blocked malicious requests never reach PHP, MySQL or WordPress, which actually reduces total server load during an attack. Keep the paranoia level sensible (PL1 for most sites) and the overhead stays negligible.

What’s the difference between ModSecurity and the OWASP CRS?

ModSecurity is the WAF engine, the software that inspects requests. The OWASP Core Rule Set is the collection of detection rules that tells the engine what an attack looks like. ModSecurity without rules does nothing useful; the CRS without an engine is just text files. You install both together: the engine plus its rulebook.

Why should I start in DetectionOnly mode?

Because every site has unique traffic, and the CRS occasionally flags legitimate requests as attacks (false positives). If you go straight to blocking mode, those false positives become real outages, broken admin pages, failed form submissions, locked-out users. DetectionOnly lets you observe what would be blocked, fix the false positives with exclusion rules, and only then enable real blocking. It’s the difference between a smooth rollout and an emergency.

What is a Paranoia Level in the OWASP CRS?

It’s a sensitivity dial from 1 to 4. PL1 catches clear, unambiguous attacks with very few false positives, the recommended default. Higher levels add increasingly aggressive rules that catch more subtle attacks but also flag more legitimate traffic. Most production sites run at PL1 or PL2. Only raise it if you understand your traffic well and have a low tolerance for risk plus the time to manage exclusions.

Do I need ModSecurity if I already use a WordPress security plugin?

They work at different layers. A PHP security plugin (Wordfence, etc.) runs inside WordPress, which means WordPress and PHP already loaded before it can act. ModSecurity blocks malicious requests at the NGINX layer, before PHP even starts. That’s far more efficient under attack and removes a whole class of risk. For performance-conscious sites, a WAF is the stronger foundation; you can still run a PHP plugin on top for file-integrity monitoring and alerting.

Will this work on Apache instead of NGINX?

Yes. ModSecurity and the OWASP CRS are server-agnostic at the rules level. The engine installation differs (Apache uses mod_security2 with its own config paths) but Steps 3–6, the base config, CRS install, main.conf wiring, and DetectionOnly-then-On rollout, are essentially identical. The CRS rules themselves are byte-for-byte the same.

How do I update the OWASP CRS later?

Since you installed it via git, updating is cd /etc/nginx/modsec/owasp-crs && sudo git pull, then sudo nginx -t && sudo systemctl reload nginx. Always test in DetectionOnly-equivalent caution after a major version bump, new rules can introduce new false positives. Subscribe to the CRS release notes so you know when security-relevant rules change.

Our optimized NGINX and Angie builds for Debian and Ubuntu ship the http-modsecurity module precompiled, turning the hardest part of this guide into a single apt install.

Most articles about zstd vs Brotli vs zlib-ng accidentally compare a fruit salad to a turbocharger. That is the first problem we are going to fix.

Brotli and Zstd are compression formats that can show up in HTTP as Content-Encoding: br and Content-Encoding: zstd. Browsers can explicitly ask for them with Accept-Encoding. zlib-ng, on the other hand, is not a new browser encoding at all. It is a modern, optimized replacement for the old zlib library that powers gzip/deflate. The browser still sees gzip. The server just spends less effort making it.

That distinction matters because it changes the answer to every practical question. If you ask, “Which one gives me the best universal compatibility?”, zlib-ng is not competing with Brotli or Zstd in the same lane. If you ask, “Which one should I send to modern browsers?”, now Brotli and Zstd are in the spotlight, and zlib-ng becomes an optimization strategy for your gzip fallback path.

This rewrite takes the original comparison article and turns it into the grown-up version. We are going deep on what each option actually changes, where it fits in our NGINX builds and our Angie builds, how static and dynamic compression differ, and which production combinations make sense when real traffic, real caches, and real CPU budgets show up to ruin the fantasy.

The one-sentence answer

If you only have patience for one paragraph, here it is:

• gzip is still the universal baseline every browser understands.
• zlib-ng makes that gzip path faster and cheaper, but does not create a new browser-visible encoding.
• Brotli usually wins on compression ratio for static text assets like CSS and JavaScript.
• Zstd offers a very attractive speed-to-ratio balance for modern clients and is increasingly practical for web delivery.
• The production answer is usually “run more than one”, not “pick one and become emotionally attached.”