Basic Configuration

This guide covers fundamental configuration patterns for the nginx-torblocker module. Start here after completing the Installation Guide.

Getting Started

After installing the module, you need to:

Load the module in Nginx
Configure basic Tor blocking
Test the configuration
Restart Nginx

Step 1: Loading the Module

First, ensure the module is loaded. Add this line to the very top of your nginx.conf file:

load_module modules/ngx_http_torblocker_module.so;

Complete minimal configuration:

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    
    # Enable Tor blocking
    torblock on;
    
    server {
        listen 80;
        server_name example.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Step 2: Basic Directives

torblock Directive

The main directive to enable or disable Tor blocking:

# Enable Tor blocking
torblock on;

# Disable Tor blocking  
torblock off;

Context: Can be used in http, server, or location blocks.

torblock_list_url Directive

Specify the URL for fetching Tor exit node lists:

# Use default (recommended)
# No configuration needed - auto-detects your server IP

# Custom URL with specific IP
torblock_list_url "https://check.torproject.org/cgi-bin/TorBulkExitList.py?ip=YOUR_SERVER_IP";

# Alternative source (if needed)
torblock_list_url "https://www.dan.me.uk/torlist/";

torblock_update_interval Directive

Set how often to update the Tor exit node list (in milliseconds):

# Default: 1 hour (3600000 milliseconds)
torblock_update_interval 3600000;

# More frequent updates: 30 minutes
torblock_update_interval 1800000;

# Less frequent updates: 6 hours
torblock_update_interval 21600000;

Common Configuration Patterns

Pattern 1: Global Blocking

Block Tor everywhere with default settings:

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    
    # Simple global blocking
    torblock on;
    
    server {
        listen 80;
        server_name mysite.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Pattern 2: Conditional Blocking

Allow Tor by default, block for specific areas:

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    
    # Default: Allow Tor
    torblock off;
    
    server {
        listen 80;
        server_name mysite.com;
        
        # Public content - Allow Tor
        location / {
            root /var/www/html;
            index index.html;
        }
        
        # Admin area - Block Tor
        location /admin {
            torblock on;
            
            root /var/www/admin;
            index index.html;
            
            auth_basic "Admin Area";
            auth_basic_user_file /etc/nginx/.htpasswd;
        }
    }
}

Pattern 3: Custom Settings

Use custom URL and update frequency:

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    
    # Custom configuration
    torblock on;
    torblock_list_url "https://check.torproject.org/cgi-bin/TorBulkExitList.py?ip=192.168.1.100";
    torblock_update_interval 1800000;  # 30 minutes
    
    server {
        listen 80;
        server_name mysite.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Quick Start Examples

Example 1: Simple Website

Scenario: Basic website that wants to block all Tor traffic.

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    # Block Tor globally
    torblock on;
    
    server {
        listen 80;
        listen [::]:80;
        server_name example.com www.example.com;
        
        root /var/www/example.com;
        index index.html index.htm;
        
        location / {
            try_files $uri $uri/ =404;
        }
        
        # Static assets
        location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

Example 2: WordPress Blog

Scenario: WordPress site with protected admin area.

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    # Default: Allow Tor for content
    torblock off;
    
    server {
        listen 80;
        server_name myblog.com www.myblog.com;
        
        root /var/www/wordpress;
        index index.php;
        
        # Public content
        location / {
            try_files $uri $uri/ /index.php?$args;
        }
        
        # Block Tor from admin area
        location /wp-admin {
            torblock on;
            try_files $uri $uri/ /index.php?$args;
        }
        
        # Block Tor from login
        location /wp-login.php {
            torblock on;
            try_files $uri =404;
            fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
            fastcgi_index index.php;
            include fastcgi_params;
        }
        
        # PHP handler
        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
            fastcgi_index index.php;
            include fastcgi_params;
        }
    }
}

Example 3: API Server

Scenario: API server with public and private endpoints.

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    # Default: Block Tor for security
    torblock on;
    
    server {
        listen 80;
        server_name api.example.com;
        
        # Public API - Allow Tor
        location /api/v1/public {
            torblock off;
            
            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
        
        # Private API - Block Tor (inherits global setting)
        location /api/v1/private {
            proxy_pass http://127.0.0.1:3001;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
        
        # Admin API - Block Tor + IP restrictions
        location /api/v1/admin {
            allow 192.168.1.0/24;
            allow 10.0.0.0/8;
            deny all;
            
            proxy_pass http://127.0.0.1:3002;
        }
    }
}

Testing Your Configuration

Step 1: Syntax Check

Always test configuration syntax before reloading:

sudo nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Step 2: Reload Configuration

sudo systemctl reload nginx

# Or restart if needed
sudo systemctl restart nginx

Step 3: Verify Module Loading

# Check for module-related errors
sudo tail -f /var/log/nginx/error.log

# Test basic functionality
curl -I http://localhost

Step 4: Test Tor Blocking

# Normal request (should work)
curl -v http://your-domain.com/

# Simulate Tor request (replace with actual Tor IP)
curl -v -H "X-Forwarded-For: 1.2.3.4" http://your-domain.com/

Configuration Validation

Check Module Status

# Verify module is loaded
sudo nginx -V 2>&1 | grep -i module

# Check configuration structure
sudo nginx -T | grep -A 5 -B 5 torblock

Monitor Blocked Requests

# Watch for blocked requests
sudo tail -f /var/log/nginx/access.log | grep " 403 "

# Count blocked requests in last hour
sudo grep "$(date '+%d/%b/%Y:%H')" /var/log/nginx/access.log | grep " 403 " | wc -l

Default Behavior

When torblock is not specified:

Default: off (Tor traffic is allowed)
Inheritance: Child contexts inherit from parent contexts

When torblock_list_url is not specified:

Default: Auto-detects your server's IP and uses Tor Project's API
URL format: https://check.torproject.org/cgi-bin/TorBulkExitList.py?ip=YOUR_IP

When torblock_update_interval is not specified:

Default: 3600000 milliseconds (1 hour)
Minimum recommended: 900000 milliseconds (15 minutes)
Maximum practical: 86400000 milliseconds (24 hours)

Common Mistakes

1. Module Not Loaded

# Wrong: Missing load_module directive
events {
    worker_connections 1024;
}

http {
    torblock on;  # This will fail!
}

# Correct: Load module first
load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    torblock on;
}

2. Wrong Module Path

# Wrong: Incorrect path
load_module /wrong/path/ngx_http_torblocker_module.so;

# Correct: Standard path
load_module modules/ngx_http_torblocker_module.so;

# Or full path if needed
load_module /usr/lib/nginx/modules/ngx_http_torblocker_module.so;

3. Invalid Time Values

# Wrong: Invalid time format
torblock_update_interval 30m;  # Not supported

# Correct: Milliseconds only
torblock_update_interval 1800000;  # 30 minutes

Performance Notes

Memory Usage

Minimal impact: ~1-5MB for Tor exit node list
Shared memory: One list shared across all workers
No per-request allocation: List is cached in memory

Request Processing

Negligible overhead: Simple IP lookup per request
No external calls: During request processing
Background updates: Tor list updates happen asynchronously

Recommended Settings for Different Loads

# Low traffic sites (< 1000 requests/day)
torblock_update_interval 7200000;  # 2 hours

# Medium traffic sites (1000-100000 requests/day)  
torblock_update_interval 3600000;  # 1 hour (default)

# High traffic sites (> 100000 requests/day)
torblock_update_interval 1800000;  # 30 minutes

# High security environments
torblock_update_interval 900000;   # 15 minutes

Next Steps

After mastering basic configuration:

Site-Specific Control: Learn Site-Specific Blocking
URL-Level Control: Explore Path-Based Blocking
Complex Scenarios: Review Advanced Configuration
Monitoring: Set up Monitoring & Logging
Performance: Optimize with Performance Tuning

Troubleshooting

If you encounter issues, see the Troubleshooting Guide for detailed solutions to common problems.

Uh oh!

Basic Configuration

Basic Configuration

Getting Started

Step 1: Loading the Module

Step 2: Basic Directives

torblock Directive

torblock_list_url Directive

torblock_update_interval Directive

Common Configuration Patterns

Pattern 1: Global Blocking

Pattern 2: Conditional Blocking

Pattern 3: Custom Settings

Quick Start Examples

Example 1: Simple Website

Example 2: WordPress Blog

Example 3: API Server

Testing Your Configuration

Step 1: Syntax Check

Step 2: Reload Configuration

Step 3: Verify Module Loading

Step 4: Test Tor Blocking

Configuration Validation

Check Module Status

Monitor Blocked Requests

Default Behavior

When torblock is not specified:

When torblock_list_url is not specified:

When torblock_update_interval is not specified:

Common Mistakes

1. Module Not Loaded

2. Wrong Module Path

3. Invalid Time Values

Performance Notes

Memory Usage

Request Processing

Recommended Settings for Different Loads

Next Steps

Troubleshooting

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally