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

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

1. Clone this repository:

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

2. 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

3. Configure and build the module:

   # Configure Nginx with the module
   ./configure --add-dynamic-module=../src
   
   # Build only the modules (not full Nginx)
   make modules

4. 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.