nginx-ultimate-bad-bot-blocker: what the install scripts actually change in your nginx config

The problem: filtering traffic before it reaches your application

Application-level blocking happens after nginx has already parsed the request, allocated a worker connection and handed it to PHP, Node or whatever sits behind the proxy. For a WordPress site being hammered by referrer spam, vulnerability scanners and fake Googlebots, that is work you pay for on every request. This project moves the decision into nginx itself. The README describes it as blocking bad bots, user agents, spam referrers, adware, malware, clickjacking and bad IPs, with an anti-DDOS system, nginx rate limiting and a WordPress theme detector block. The intended reader is someone running nginx on a Linux or FreeBSD host, comfortable editing server config files and running shell scripts as root. It is not a hosted service and there is no dashboard. Everything is a file on disk that nginx includes at startup or reload.

The scale is stated in the README: version V4.2026.09.6157, 7116 bad referrers, 700 bad user agents and 218 fake Googlebots, each list linked from the README to a raw file under _generator_lists/. Those numbers matter because they set the maintenance model. The lists are regenerated rather than hand-curated, and the README asks users to subscribe to GitHub notifications so they hear about updates and about changes it calls potentially breaking.

How the blocker is wired into nginx: include files, load order and the whitelist at the end

The repository is laid out as directories of nginx include fragments: conf.d/, bots.d/, deny.d/, headers.d/, ssl.d/ and scripts.d/, alongside the install-ngxblocker, setup-ngxblocker and update-ngxblocker scripts. The mechanism is ordinary nginx include behaviour. Fragments are pulled into the http or server context, and the order in which they load determines the outcome. The README is explicit about that order for the global blocklist: daily updates can blacklist well known IPs and ranges, and those are then whitelisted at the very end of globalblocklist, which sets the known-good IPs back to value 0.

That design produces a side effect the README addresses head on under a [WARN] heading. Reloading nginx with the same IP appearing twice, once blocked and once whitelisted, emits duplicate network messages. The README states this is not a bug, cannot be fixed, and is the desired behaviour, and that these are [WARN] not [EMERG] messages that do not affect nginx operation. Take that at face value: it is a real consequence of list-based filtering with an override layer, and anyone who greps their error log for warnings after a reload will meet it. The project also ships a Fail2Ban addon under _fail2ban_addon/ for repeat offenders, a separate mechanism from the static lists, aimed at clients that keep coming back.

Installing it with install-ngxblocker and running setup-ngxblocker

The README calls the shell scripts the preferred installation method and credits them to Stuart Cardall, an Alpine Linux package maintainer. The first step downloads install-ngxblocker into /usr/local/sbin/ and marks it executable. The README gives wget and a curl equivalent.

sudo wget https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/install-ngxblocker -O /usr/local/sbin/install-ngxblocker
sudo chmod +x /usr/local/sbin/install-ngxblocker

On FreeBSD the README gives a package instead: pkg install www/nginx-ultimate-bad-bot-blocker. After the script is in place, setup-ngxblocker is the one that does the config work. The README states the setup script assumes vhost config files live in /etc/nginx/sites-available/ and that each vhost file ends in the extension .vhost, and that the scripts add the required includes to nginx.conf and to the vhost files. If your layout differs, the README says setup-ngxblocker, install-ngxblocker and update-ngxblocker accept custom installation and update locations from the command line, and points to step 11 of its instructions for non-standard nginx locations. All three scripts respond to --help or -h.

sudo setup-ngxblocker --help
sudo setup-ngxblocker

The README also notes that the project was tested on nginx 1.10.x and later mainstream versions. For anyone using Let's Encrypt, it recommends the webroot authenticator method and says the http challenge method has caused problems, with the cause unclear. Manual installation is documented separately in MANUAL-CONFIGURATION.md, which is the file to read if you would rather not have a script edit your server blocks.

Where the blocker is the wrong tool

The setup script's assumptions are the first limitation. Vhosts in /etc/nginx/sites-available/ ending in .vhost is a Debian-shaped convention. On a host where server blocks live in /etc/nginx/conf.d/ or are generated by a control panel, the automatic path does not match reality, and the README does not describe what the script does when it finds nothing to edit. Custom locations are supported through command line options, but the README does not document rollback. There is no documented uninstall step, so the include lines added to nginx.conf and your vhosts are something you should record before running setup.

The second limitation is that filtering by user agent and referrer is a heuristic. A blocked user agent string is trivially changed by a client that wants in, and a legitimate crawler that adopts a new agent string can be caught by a list before anyone notices. The README's own framing of fake Googlebots shows the trade-off: 218 entries exist to catch impersonators, and the whitelist layer exists because broad IP blocking catches real traffic too. If your site depends on traffic from sources that look like scanners or spam referrers, you will be tuning rather than simply installing. The duplicate warning messages on reload are also a permanent fixture, not a phase you pass through.

Apache Ultimate Bad Bot Blocker and nginx rate limiting as the two comparisons that matter

The README's own alternative is the Apache Ultimate Bad Bot Blocker, by the same author. The difference is not the list content but the enforcement layer. Apache applies its rules through .htaccess or server config directives, which suits shared hosting and per-directory overrides, while this project is built around nginx include fragments and the http and server contexts, where per-directory overrides do not exist. If your stack is Apache, the nginx version is simply inapplicable, and the README says so directly.

The second comparison is native nginx rate limiting. The project's topics include NGINX rate limiting, and the README describes an anti-DDOS system and rate limiting as part of the package. Native nginx limit_req and limit_conn directives do one thing: they cap request and connection rates per key. They do not know which user agents are undesirable, they carry no referrer list, and they need no daily updates. The blocker adds the curated lists and the Fail2Ban jail on top of that primitive. If all you need is to stop one client from opening hundreds of connections, the built-in directives are sufficient and have no update cycle to maintain. If you need to reject a named class of traffic before it reaches the application, that is the gap this project fills.

Maintenance cost, licence and what to verify before you commit

The last push to the repository was on 2026-09-22, and the repository is not archived, so the project is current. That currency is also the maintenance burden. The README asks users to subscribe to GitHub notifications so they are told when the blocker is updated and when changes it labels potentially breaking take place, and it ships update-ngxblocker for that purpose. In practice you are adopting a dependency whose data changes daily and whose version string, V4.2026.09.6157, encodes the update cadence. Plan for a scheduled update and a reload, and expect the reload to print the duplicate network warnings described above.

The licence file is LICENSE.md and the repository's licence metadata is NOASSERTION, meaning GitHub could not map it to a standard identifier. Read LICENSE.md directly rather than assuming an OSI licence. For a script set that edits your web server configuration and ships generated blocklists, the terms governing redistribution and modification are worth checking before you bundle it into an image or a configuration management role. Nothing here is legal advice; the point is that the metadata does not answer the question.

Editorial conclusion

Adopt it if you run nginx from distribution packages on a host you control, keep your vhosts in /etc/nginx/sites-available/ with .vhost extensions, and accept that the globalblocklist loads whitelists last, which produces the documented duplicate network warnings. Do not adopt it if you manage nginx only through containers or a control panel, because the setup scripts assume standard file locations and the README documents no Docker path. Before installing, read MANUAL-CONFIGURATION.md and confirm which include lines the scripts will add to your nginx.conf and vhost files, since that edit is the part hardest to undo.

Frequently asked questions

Official sources

1. Issues
2. mitchellkrogza/nginx-ultimate-bad-bot-blocker on GitHub
3. README