README

Apache, Nginx, IIS, uWSGI, Caddy, Varnish, HAProxy & Lighttpd blacklist + Google Analytics segments to prevent referrer spam traffic

Apache: .htaccess

.htaccess is a configuration file for use on web servers running Apache. This file is usually found in the root “public_html” folder of your website. The .htaccess file uses two modules to prevent referral spam, mod_rewrite and mod_setenvif. Decide which method is most suitable with your Apache server configuration. This file is Apache 2.4 ready, where mod_authz_host got deprecated.

Nginx: referral-spam.conf

IMPORTANT: You must increase the map hash bucket size to support the large domain list. With referral-spam.conf in /etc/nginx, include it globally from within /etc/nginx/nginx.conf:

http {
	map_hash_bucket_size 128;
	include referral-spam.conf;
}

Add the following to each /etc/nginx/site-available/your-site.conf that needs protection:

server {
	if ($bad_referer) {
		return 444;
	}
}

Performance Note: This configuration uses a performance-optimized approach with hostname matching instead of thousands of regex patterns. Only one regex is evaluated per request to extract the domain from the Referer header, significantly improving NGINX performance compared to traditional regex-based blocking methods.

Varnish: .refferal-spam.vcl

Add referral-spam.vcl to Varnish 4 default file: default.vcl by adding the following code right underneath your default backend definitions

include "referral-spam.vcl";
sub vcl_recv { call block_referral_spam; }

IIS (Internet Information Services): web.config

The web.config file is located in the root directory of your Windows Server web application.

Caddy (HTTP/2 Web Server with Automatic HTTPS): referral-spam.caddy and referral-spam.caddy2

Move this file next to your Caddy config file, and include it by doing:

# For Caddy 1:
 include ./referral-spam.caddy;
# For Caddy 2:
 import ./referral-spam.caddy2

Then start your caddy server. All the referrers will now be redirected to a 444 HTTP answer

uWSGI: referral_spam.res

Include the file referral_spam.res into your vassal .ini configuration file:

ini = referral_spam.res:blacklist_spam

HAProxy: referral-spam.haproxy

Use it in your HAProxy config by adding all domains.txt items, in any frontend, listen or backend block:

acl spam_referer hdr_sub(referer) -i -f /etc/haproxy/referral-spam.haproxy
http-request deny if spam_referer

Lighttpd: referral-spam.lighttpd.conf

Include this file in your main lighttpd.conf:

include "referral-spam.lighttpd.conf"

Make sure mod_rewrite is enabled in your server.modules:

server.modules = ("mod_rewrite", ...)

The configuration blocks referrer spam by redirecting requests with spam referrers. For better performance with large domain lists, consider using mod_magnet.

OpenLiteSpeed: .htaccess

OpenLiteSpeed is Apache-compatible and supports .htaccess files. Simply use the Apache .htaccess file (see Apache section above).

Make sure mod_rewrite is enabled in your OpenLiteSpeed configuration:

• Admin Panel > Server > Modules > mod_rewrite (enable)

Options for Google Analytics 'ghost' spam

The above methods don't stop the Google Analytics ghost referral spam (because they are hitting Analytics directly and don't touching your website). You should use filters in Analytics to prevent ghost referral spam and hide spam form the past. Because Google Analytics segments are limited to 30.000 characters the exclude list is separated into multiple parts.

Navigate to your Google Analytics Admin panel and add these Segments:

Do the same for google-exclude-2.txt. Please note there may be more files in the future.

You can also prevent ghost referral spam by:

• Adding a filter
• Enabeling bot and Spider Filtering

Command Line Interface

# Basic usage
php run.php
php run.php --types apache,nginx
php run.php --dry-run
php run.php --output /path/to/configs

# Options: -h (help), -v (version), --dry-run, -o (output), -t (types)
# Supported types: apache, nginx, varnish, iis, uwsgi, caddy, caddy2, haproxy, lighttpd, google

Testing

The project includes comprehensive testing and code quality tools:

# Run tests
composer test
composer test-coverage

# Code quality
composer phpstan
composer phpcs
composer phpcbf
composer quality

Tests cover unit testing, configuration generation, domain processing, and file operations. Quality tools include PHPStan (Level 8), PHP CodeSniffer (PSR-12), and Psalm for static analysis.

Programmatic Usage

use StevieRay\Generator;

$generator = new Generator('/path/to/output');
$generator->generateFiles();
$generator->generateSpecificConfigs(['apache', 'nginx']);
$stats = $generator->getStatistics();

Intregrate in a Dockerfile

You can also integrate these configuration file in your Docker repo, so you will get always the most updated version when you build your image. For Apache, Nginx, Varnish 4 or IIS add the following line to your Dockerfile

# Apache: Download .htaccess to /usr/local/apache2/htdocs/
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/.htaccess /usr/local/apache2/htdocs/

# Nginx: Download referral-spam.conf to /etc/nginx/
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral-spam.conf /etc/nginx/

# Varnish 4: Download referral-spam.vcl to /etc/varnish/
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral-spam.vcl /etc/varnish/

# IIS: Download web.config to /sitepath/ (change sitepath accordingly)
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/web.config /sitepath/

# Caddy: Download referral-spam.caddy to /sitepath/ (next to your Caddy config file given through -conf)
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral-spam.caddy /sitepath/

# uWSGI: Download referral_spam.res to /sitepath/ (change sitepath accordingly)
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral_spam.res /sitepath/

# HAProxy: Download referral-spam.haproxy to /etc/haproxy/
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral-spam.haproxy /etc/haproxy/

# Lighttpd: Download referral-spam.lighttpd.conf to /etc/lighttpd/
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/referral-spam.lighttpd.conf /etc/lighttpd/

# OpenLiteSpeed: Use the Apache .htaccess file (OpenLiteSpeed is Apache-compatible)
ADD https://raw.githubusercontent.com/Stevie-Ray/referrer-spam-blocker/master/.htaccess /sitepath/

Like it?

• Buy me a beer 🍺