Nginx TorBlocker

A simple Nginx module to block access from Tor exit nodes.

Features

Blocks requests from Tor exit nodes
Regularly updates the list of Tor exit nodes
Easy to configure and integrate with Nginx
Per-location and per-server configuration

Documentation & Support

📖 Complete Documentation - Comprehensive guides, tutorials, and reference materials

💬 Community Discussions - Ask questions, share experiences, and get help from the community

Quick Links to Wiki Articles

🏠 Home - Overview and getting started
📦 Installation Guide - Step-by-step installation instructions
🔨 Building from Source - Compile the module yourself
📋 Configuration Reference - Complete directive documentation
⚙️ Basic Configuration - Simple setup examples
🚀 Advanced Configuration - Complex policies and patterns
🔗 Context Hierarchy - Understanding configuration inheritance
🎯 Site-Specific Blocking - Per-site configuration
🛣️ Path-Based Blocking - URL-specific rules
🌐 Server-Wide Blocking - Global configuration
🔀 Mixed Policies - Combining different approaches
📥 Module Loading - Loading and initializing the module
🧪 Testing Procedures - Validate functionality and performance
🔧 Troubleshooting Guide - Solve common issues
⚡ Performance Tuning - Optimize for your environment
📊 Monitoring & Logging - Observability and metrics
🛠️ Development Setup - Contributing and development environment

Repository Structure

src/ — Nginx module source code
debian/ — Packaging files (for building .deb packages)
conf/ — Example configuration

Installation

Package Installation (Recommended)

Pre-built packages are available for multiple Linux distributions via the openSUSE Build Service.

Debian / Ubuntu

# Add the repository
echo "deb http://download.opensuse.org/repositories/home:/rumenx/xUbuntu_24.04/ /" | sudo tee /etc/apt/sources.list.d/nginx-torblocker.list

# Add the repository key
curl -fsSL https://download.opensuse.org/repositories/home:/rumenx/xUbuntu_24.04/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/nginx-torblocker.gpg > /dev/null

# Update and install
sudo apt update
sudo apt install nginx-torblocker

Supported Versions:

Ubuntu 24.04 (Noble) - Use xUbuntu_24.04
Ubuntu 22.04 (Jammy) - Use xUbuntu_22.04
Debian 12 (Bookworm) - Use Debian_12
Debian 13 (Trixie) - Use Debian_13

Replace xUbuntu_24.04 in the commands above with your distribution version.

Fedora

# Add the repository
sudo dnf config-manager --add-repo https://download.opensuse.org/repositories/home:/rumenx/Fedora_41/home:rumenx.repo

# Install the package
sudo dnf install nginx-torblocker

Supported Versions:

Fedora 42 - Use Fedora_42
Fedora 41 - Use Fedora_41

openSUSE

# Add the repository
sudo zypper addrepo https://download.opensuse.org/repositories/home:/rumenx/openSUSE_Tumbleweed/home:rumenx.repo

# Refresh repositories
sudo zypper refresh

# Install the package
sudo zypper install nginx-torblocker

Supported Versions:

openSUSE Tumbleweed - Use openSUSE_Tumbleweed
openSUSE Leap 15.6 - Use openSUSE_Leap_15.6
openSUSE Leap 16.0 - Use openSUSE_Leap_16.0

RHEL / CentOS / Rocky Linux / AlmaLinux

# Add the repository (RHEL 9 example)
sudo dnf config-manager --add-repo https://download.opensuse.org/repositories/home:/rumenx/RHEL_9/home:rumenx.repo

# Install the package
sudo dnf install nginx-torblocker

Supported Versions:

RHEL/CentOS 7 - Use RHEL_7

After Installation

After installing the package, the module will be installed to:

Debian/Ubuntu: /usr/lib/nginx/modules/ngx_http_torblocker_module.so
Fedora/RHEL/openSUSE: /usr/lib64/nginx/modules/ngx_http_torblocker_module.so

Load the module by adding to the top of your /etc/nginx/nginx.conf:

load_module modules/ngx_http_torblocker_module.so;

Then restart nginx:

sudo systemctl restart nginx

Quick Build Instructions

📖 For detailed build instructions and installation guides, see the Building from Source and Installation Guide wiki pages.

💾 Pre-built packages are available on the Releases page for Ubuntu 22.04/24.04/25.04 with various Nginx versions.

Prerequisites

Nginx installed on your system
Nginx source code matching your installed version
Build tools: gcc, make, wget
Development libraries: libpcre3-dev, zlib1g-dev

You can install the prerequisites on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential gcc libpcre3-dev zlib1g-dev wget

On CentOS/RHEL:

sudo yum groupinstall "Development Tools"
sudo yum install pcre-devel zlib-devel wget

Build the Module

Clone this repository:

git clone https://github.com/RumenDamyanov/nginx-torblocker.git
cd nginx-torblocker

Download and extract the Nginx source for your version:

# Check your Nginx version first
nginx -v

# Download matching source (example for 1.26.0)
wget https://nginx.org/download/nginx-1.26.0.tar.gz
tar xzf nginx-1.26.0.tar.gz
cd nginx-1.26.0

Configure and build the module:

# Configure Nginx with the module
./configure --add-dynamic-module=../src

# Build only the modules (not full Nginx)
make modules

Install the module:

# Copy to your Nginx modules directory
sudo cp objs/ngx_http_torblocker_module.so /usr/lib/nginx/modules/

# Or to a custom location
sudo cp objs/ngx_http_torblocker_module.so /etc/nginx/modules/

Load the Module in Nginx

Add to the top of your nginx.conf:

load_module modules/ngx_http_torblocker_module.so;

Configuration Example

See conf/test.conf for a full example. Basic usage:

http {
    torblock on;
}

Configuration Reference

📋 For complete configuration details, see the Configuration Reference wiki page.

Directives

Directive	Context	Default	Description
`torblock`	http, server, location	`off`	Enable/disable Tor blocking
`torblock_list_url`	http, server, location	Auto-detected	URL for Tor exit node list
`torblock_update_interval`	http, server, location	`3600000`	Update interval in milliseconds (1 hour)

Context Hierarchy

The module supports configuration at three levels with inheritance:

HTTP context: Global default for all servers
Server context: Per virtual host settings
Location context: Per URL path settings

Child contexts inherit from parent contexts, and more specific settings override general ones.

📖 Learn more about Context Hierarchy in the wiki.

Usage Examples

🚀 For advanced configuration examples, see the Advanced Configuration wiki page.

Basic Configuration

http {
    # Enable globally with defaults
    torblock on;
}

Advanced Configuration

http {
    # Configure custom settings
    torblock on;
    torblock_list_url "https://check.torproject.org/cgi-bin/TorBulkExitList.py?ip=$remote_addr";
    torblock_update_interval 600000; # 10 minutes

    # Per-server configuration
    server {
        torblock off; # Disable for specific server

        # Per-location configuration
        location /api {
            torblock on; # Re-enable for specific location
        }
    }
}

Block Tor access except for specific IP

http {
    torblock on;

    # Allow specific IP even if it's a Tor exit node
    geo $allow_tor {
        default 0;
        192.168.1.100 1;
    }

    server {
        if ($allow_tor) {
            set $torblock "off";
        }
    }
}

Combining Global, Server, and Location Settings

You can enable or disable the module at different levels for flexible access control. For example:

http {
    torblock off; # Default: allow Tor everywhere

    # Enable Tor blocking only for a specific vhost
    server {
        server_name sensitive.example.com;
        torblock on; # Block Tor for this vhost

        # But allow Tor for a specific location (e.g., public API)
        location /public-api {
            torblock off;
        }
    }

    # Another vhost with default (Tor allowed)
    server {
        server_name open.example.com;
        # torblock remains off
    }
}

Use case:

This setup is helpful if you want to block Tor for sensitive parts of your site (e.g., admin panels or private content) but allow Tor users to access public APIs or open resources. You can also have some vhosts open to Tor and others protected, all in the same Nginx instance.

Troubleshooting

🔧 For comprehensive troubleshooting guides, see:

Troubleshooting Guide - Detailed diagnostic procedures and solutions
Testing Procedures - Validate your configuration and performance
Performance Tuning - Optimize for your environment

💬 Need help? Visit our Community Discussions to ask questions and get support.

Common Issues

Module fails to load

nginx: [emerg] dlopen() "/usr/lib/nginx/modules/ngx_http_torblocker_module.so" failed

Solutions:

Ensure the module was built against the same Nginx version you're running
Check file permissions: chmod 644 /usr/lib/nginx/modules/ngx_http_torblocker_module.so
Verify the module path in your load_module directive

Configuration test fails

nginx: [emerg] unknown directive "torblock"

Solutions:

Ensure load_module directive is at the top of nginx.conf (before any http block)
Verify the module file exists and is readable
Check Nginx error logs for detailed error messages

Module version mismatch

nginx: [emerg] module "/usr/lib/nginx/modules/ngx_http_torblocker_module.so" version 1024000 instead of 1026000

Solutions:

Rebuild the module against your exact Nginx version
Download the correct Nginx source version with nginx -v

Performance Considerations

Memory usage: The module maintains an in-memory list of Tor exit nodes
Update frequency: Default 1-hour updates balance freshness with performance
Request overhead: Minimal impact - simple IP lookup per request
Concurrent requests: Module is thread-safe for multi-worker configurations

Debugging

Enable debug logging in Nginx:

error_log /var/log/nginx/debug.log debug;

Check for module-specific messages:

grep torblock /var/log/nginx/error.log

Background & Inspiration

This module is inspired by a PHP script I developed over 20 years ago called AntiTor, which successfully blocked Tor access to web servers. The original script was effective but limited in scope.

The nginx-torblocker module brings this concept into the modern era with several key improvements:

Native performance: Runs at the Nginx level instead of PHP application layer
Granular control: Enable/disable blocking per virtual host or location
Selective access: Allow Tor for public resources while blocking sensitive areas
Multi-site support: Different policies for multiple sites on the same server
Automatic updates: Keeps Tor exit node lists current without manual intervention

This refined approach allows for sophisticated access control policies that weren't possible with the original script, making it suitable for complex hosting environments where different sites may have different security requirements.

Binary Packages & Distribution

Official Distribution

The primary distribution channel for pre-built binaries is the GitHub Releases page, which provides:

Binary packages for Ubuntu 22.04 LTS (jammy), 24.04 LTS (noble), and 25.04 (plucky)
Multiple architectures: amd64 and arm64
Multiple nginx versions: Compatible with nginx 1.26.x and 1.27.x series
Debian packages (.deb) for native installation via dpkg

PPA Status

The experimental Ubuntu PPA is no longer supported and has been discontinued. It was never an official distribution channel and proved unreliable for production use.

Future Plans

A self-hosted apt repository is planned to provide signed, reproducible builds without third-party hosting constraints. This repository will host multiple packages from our projects and will target:

Ubuntu 24.04 LTS (noble) and newer versions
Ubuntu 25.04 (plucky) and newer versions

For now, please use the official GitHub Releases or build from source.

Contributing

We welcome contributions! Please see our Contributing Guide for detailed information on:

Setting up the development environment
Coding guidelines and best practices
Testing procedures
Pull request process

Please also read our Code of Conduct before participating.

🗣️ Join the conversation: Use our Community Discussions to:

Propose new features or improvements
Share your use cases and configurations
Get help with development setup
Connect with other contributors and users

Security

Security is important to us. If you discover a security vulnerability, please see our Security Policy for information on how to report it responsibly.

Funding

If you find this project useful, please consider supporting its development. See FUNDING.md for information about sponsorship and donations.

License

BSD License. See LICENSE.md.

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github		.github
conf		conf
debian		debian
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FUNDING.md		FUNDING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md

Uh oh!

License

RumenDamyanov/nginx-torblocker

Folders and files

Latest commit

History

Repository files navigation

Nginx TorBlocker

Features

Documentation & Support

Quick Links to Wiki Articles

Repository Structure

Installation

Package Installation (Recommended)

Debian / Ubuntu

Fedora

openSUSE

RHEL / CentOS / Rocky Linux / AlmaLinux

After Installation

Quick Build Instructions

Prerequisites

Build the Module

Load the Module in Nginx

Configuration Example

Configuration Reference

Directives

Context Hierarchy

Usage Examples

Basic Configuration

Advanced Configuration

Block Tor access except for specific IP

Combining Global, Server, and Location Settings

Troubleshooting

Common Issues

Module fails to load

Configuration test fails

Module version mismatch

Performance Considerations

Debugging

Background & Inspiration

Binary Packages & Distribution

Official Distribution

PPA Status

Future Plans

Contributing

Security

Funding

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Sponsor this project

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages