How to Block Referrer Spam in Nginx: Simple Guide

To block referrer spam in nginx, use the map directive to identify bad referrers and then deny requests from them with if and return 403. This method filters unwanted traffic by matching referrer patterns and blocking them efficiently.

Syntax

The main parts to block referrer spam in nginx are:

• map $http_referer $bad_referer: Creates a variable that flags bad referrers.
• if ($bad_referer): Checks if the request comes from a bad referrer.
• return 403;: Denies access by returning HTTP 403 Forbidden.

This setup lets you list unwanted referrer patterns and block them cleanly.

nginx

map $http_referer $bad_referer {
    default 0;
    ~*badreferrer\.com 1;
    ~*spamdomain\.net 1;
}

server {
    listen 80;
    server_name example.com;

    if ($bad_referer) {
        return 403;
    }

    location / {
        # normal processing
    }
}

Example

This example blocks requests with referrers containing badreferrer.com or spamdomain.net. When a request comes from these referrers, Nginx returns a 403 Forbidden error, stopping unwanted traffic.

nginx

map $http_referer $bad_referer {
    default 0;
    ~*badreferrer\.com 1;
    ~*spamdomain\.net 1;
}

server {
    listen 80;
    server_name example.com;

    if ($bad_referer) {
        return 403;
    }

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

Output

When a request with a referrer header containing 'badreferrer.com' or 'spamdomain.net' is received, the server responds with HTTP 403 Forbidden. Other requests are served normally.

Common Pitfalls

• Using if inside location blocks incorrectly can cause unexpected behavior; place if at the server level.
• Not escaping dots in domain names (use \.) causes regex to match wrong patterns.
• Forgetting ~* makes regex case-sensitive, missing some spam referrers.
• Blocking too broadly can deny legitimate traffic; test patterns carefully.

nginx

map $http_referer $bad_referer {
    default 0;
    badreferrer.com 1;  # WRONG: missing regex and escape
}

server {
    listen 80;
    server_name example.com;

    if ($bad_referer) {
        return 403;
    }

    location / {
        # normal processing
    }
}

# Correct way:
map $http_referer $bad_referer {
    default 0;
    ~*badreferrer\.com 1;
}

server {
    listen 80;
    server_name example.com;

    if ($bad_referer) {
        return 403;
    }

    location / {
        # normal processing
    }
}

Quick Reference

• map: Define bad referrer patterns with regex.
• if ($bad_referer): Check if request matches bad referrer.
• return 403;: Block the request with forbidden status.
• Escape dots in domains with \..
• Use ~* for case-insensitive matching.

Key Takeaways

Use the nginx map directive to flag bad referrers with regex patterns.

Block flagged referrers by returning HTTP 403 using an if condition at the server level.

Always escape dots in domain names and use case-insensitive regex (~*).

Avoid placing if conditions inside location blocks to prevent config issues.

Test your referrer patterns carefully to avoid blocking legitimate traffic.