Skip to content

Configuration Reference

Jump to bottom
Rumen Damyanov edited this page Aug 23, 2025 · 1 revision

Configuration Reference

This comprehensive reference documents all nginx-torblocker directives, their syntax, valid contexts, default values, and detailed usage examples.

Overview

The nginx-torblocker module provides directives for controlling Tor exit node blocking at various levels of the Nginx configuration hierarchy. Each directive has specific contexts where it can be used and particular syntax requirements.

Directive Summary

Directive Context Default Description
torblock http, server, location off Enable/disable Tor blocking
torblock_action http, server, location 403 Action to take when Tor is detected
torblock_cache_size http 1m Size of IP cache memory
torblock_update_interval http 3600000 Update interval in milliseconds
torblock_exit_list_url http (built-in) URL for Tor exit list
torblock_redirect_url http, server, location - Redirect URL for Tor users
torblock_timeout http 30000 Request timeout in milliseconds
torblock_user_agent http (default) User agent for exit list requests
torblock_debug http off Enable debug logging

Core Directives

torblock

Syntax: torblock on | off
Default: torblock off
Context: http, server, location

Enables or disables Tor blocking for the current context.

Examples:

# Enable globally
http {
    torblock on;
}

# Enable for specific server
server {
    server_name secure.example.com;
    torblock on;
}

# Enable for specific location
location /admin {
    torblock on;
}

# Disable for public content
location /public {
    torblock off;
}

Inheritance Behavior:

http {
    torblock on;  # HTTP level: ON
    
    server {
        # Inherits: ON (from http)
        
        location / {
            # Inherits: ON (from server/http)
        }
        
        location /public {
            torblock off;  # Override: OFF
        }
    }
    
    server {
        torblock off;  # Server level: OFF
        
        location /admin {
            torblock on;  # Override: ON
        }
    }
}

torblock_action

Syntax: torblock_action 403 | 444 | 503 | redirect | log | pass
Default: torblock_action 403
Context: http, server, location

Specifies the action to take when a Tor exit node is detected.

Action Types:

  • 403: Return HTTP 403 Forbidden
  • 444: Drop connection (Nginx-specific)
  • 503: Return HTTP 503 Service Unavailable
  • redirect: Redirect to specified URL
  • log: Log access but allow request
  • pass: Allow request (monitoring only)

Examples:

# Return 403 Forbidden (default)
location /secure {
    torblock on;
    torblock_action 403;
}

# Drop connection immediately
location /admin {
    torblock on;
    torblock_action 444;
}

# Redirect to information page
location /banking {
    torblock on;
    torblock_action redirect;
    torblock_redirect_url "/tor-notice.html";
}

# Log but allow access
location /public {
    torblock on;
    torblock_action log;
}

# Monitor without blocking
location /api {
    torblock on;
    torblock_action pass;
}

torblock_cache_size

Syntax: torblock_cache_size size
Default: torblock_cache_size 1m
Context: http

Sets the size of the shared memory cache for storing Tor exit node IPs.

Size Units:

  • k or K: kilobytes
  • m or M: megabytes
  • g or G: gigabytes

Examples:

# Small cache for low-traffic sites
http {
    torblock_cache_size 512k;
}

# Medium cache for moderate traffic
http {
    torblock_cache_size 5m;
}

# Large cache for high-traffic sites
http {
    torblock_cache_size 50m;
}

# Very large cache for enterprise
http {
    torblock_cache_size 1g;
}

Cache Sizing Guidelines:

# Based on expected Tor exit nodes and traffic
http {
    # ~1000 exit nodes: 512k - 1m
    # ~2000 exit nodes: 1m - 5m
    # ~5000 exit nodes: 5m - 20m
    # ~10000+ exit nodes: 20m+
    
    torblock_cache_size 10m;  # Recommended for most sites
}

torblock_update_interval

Syntax: torblock_update_interval time
Default: torblock_update_interval 3600000
Context: http

Sets the interval for updating the Tor exit node list, in milliseconds.

Time Examples:

# 5 minutes (300,000 ms)
http {
    torblock_update_interval 300000;
}

# 30 minutes (1,800,000 ms) 
http {
    torblock_update_interval 1800000;
}

# 1 hour (3,600,000 ms) - default
http {
    torblock_update_interval 3600000;
}

# 6 hours (21,600,000 ms)
http {
    torblock_update_interval 21600000;
}

# 24 hours (86,400,000 ms)
http {
    torblock_update_interval 86400000;
}

Update Strategy:

http {
    # High-security: frequent updates
    torblock_update_interval 300000;  # 5 minutes
    
    # Balanced: moderate updates
    torblock_update_interval 1800000; # 30 minutes
    
    # Performance-focused: less frequent updates
    torblock_update_interval 21600000; # 6 hours
}

torblock_exit_list_url

Syntax: torblock_exit_list_url url
Default: (built-in Tor Project URL)
Context: http

Specifies the URL for fetching the Tor exit node list.

Examples:

# Use official Tor Project list (default)
http {
    torblock_exit_list_url "https://check.torproject.org/torbulkexitlist";
}

# Use custom or cached list
http {
    torblock_exit_list_url "https://your-cdn.example.com/tor-exits.txt";
}

# Use local mirror for better performance
http {
    torblock_exit_list_url "https://mirror.local/tor-exit-nodes";
}

# Use multiple sources (first available)
http {
    torblock_exit_list_url "https://primary.example.com/exits,https://backup.example.com/exits";
}

torblock_redirect_url

Syntax: torblock_redirect_url url
Default: (none)
Context: http, server, location

Sets the URL for redirecting Tor users when torblock_action is set to redirect.

Examples:

# Global redirect URL
http {
    torblock_redirect_url "/tor-notice.html";
    
    server {
        server_name banking.example.com;
        
        location /secure {
            torblock on;
            torblock_action redirect;
            # Uses global redirect URL
        }
    }
}

# Server-specific redirect
server {
    server_name shop.example.com;
    torblock_redirect_url "/shop-tor-notice";
    
    location /checkout {
        torblock on;
        torblock_action redirect;
    }
}

# Location-specific redirect
location /admin {
    torblock on;
    torblock_action redirect;
    torblock_redirect_url "/admin-access-denied";
}

# External redirect
location /payment {
    torblock on;
    torblock_action redirect;
    torblock_redirect_url "https://help.example.com/tor-policy";
}

Advanced Directives

torblock_timeout

Syntax: torblock_timeout time
Default: torblock_timeout 30000
Context: http

Sets the timeout for fetching the Tor exit list, in milliseconds.

Examples:

# Short timeout for fast networks
http {
    torblock_timeout 10000;  # 10 seconds
}

# Standard timeout
http {
    torblock_timeout 30000;  # 30 seconds
}

# Long timeout for slow connections
http {
    torblock_timeout 60000;  # 60 seconds
}

torblock_user_agent

Syntax: torblock_user_agent string
Default: torblock_user_agent "nginx-torblocker/1.0"
Context: http

Sets the User-Agent header for requests to the Tor exit list URL.

Examples:

# Default user agent
http {
    torblock_user_agent "nginx-torblocker/1.0";
}

# Custom user agent
http {
    torblock_user_agent "MyServer/1.0 (nginx-torblocker)";
}

# Mimic browser user agent
http {
    torblock_user_agent "Mozilla/5.0 (compatible; nginx-torblocker)";
}

torblock_debug

Syntax: torblock_debug on | off
Default: torblock_debug off
Context: http

Enables debug logging for the Tor blocking module.

Examples:

# Enable debug logging
http {
    torblock_debug on;
    error_log /var/log/nginx/error.log debug;
}

# Production configuration (debug off)
http {
    torblock_debug off;
    error_log /var/log/nginx/error.log warn;
}

Variables Reference

The module provides several variables for use in configurations:

$torblock_status

Contains the current Tor status for the request.

Values:

  • blocked: IP is a known Tor exit node
  • clean: IP is not a known Tor exit node
  • unknown: Status could not be determined

Examples:

# Add header with Tor status
location / {
    add_header X-Tor-Status $torblock_status always;
}

# Conditional processing based on status
location /api {
    if ($torblock_status = "blocked") {
        return 429 "Rate limited for Tor users";
    }
}

# Log Tor status
log_format torblock '$remote_addr - [$time_local] '
                   '"$request" $status '
                   'tor_status="$torblock_status"';

$torblock_exit_node

Contains the exit node IP if the request is from Tor.

Examples:

# Log exit node information
access_log /var/log/nginx/tor-exits.log 
          '$remote_addr via_exit=$torblock_exit_node [$time_local] "$request"';

# Add exit node header
location /debug {
    add_header X-Tor-Exit-Node $torblock_exit_node always;
}

$torblock_cache_status

Indicates whether the lookup was served from cache.

Values:

  • hit: Served from cache
  • miss: Not in cache, performed lookup
  • expired: Cache entry expired, refreshed

Examples:

# Monitor cache performance
log_format cache_perf '$remote_addr [$time_local] '
                     'cache_status=$torblock_cache_status '
                     'lookup_time=$torblock_lookup_time';

# Add cache status header for debugging
location /debug {
    add_header X-Cache-Status $torblock_cache_status always;
}

$torblock_lookup_time

Time taken for the Tor lookup in milliseconds.

Examples:

# Performance monitoring
log_format perf '$remote_addr [$time_local] '
               'lookup_time=${torblock_lookup_time}ms';

# Alert on slow lookups
location / {
    if ($torblock_lookup_time > 1000) {
        access_log /var/log/nginx/slow-tor-lookups.log combined;
    }
}

Configuration Patterns

Basic Server Protection

http {
    # Basic Tor blocking configuration
    torblock on;
    torblock_cache_size 5m;
    torblock_update_interval 1800000;  # 30 minutes
    
    server {
        listen 80;
        server_name example.com;
        
        # Allow public content
        location /public {
            torblock off;
        }
        
        # Block admin area
        location /admin {
            torblock on;
            torblock_action 403;
        }
        
        # Redirect for sensitive areas
        location /account {
            torblock on;
            torblock_action redirect;
            torblock_redirect_url "/tor-notice.html";
        }
    }
}

High-Performance Configuration

http {
    # Optimized for performance
    torblock on;
    torblock_cache_size 50m;           # Large cache
    torblock_update_interval 21600000; # 6 hours
    torblock_timeout 10000;            # Fast timeout
    
    # Performance logging
    log_format perf '$remote_addr [$time_local] '
                   '"$request" $status '
                   'cache=$torblock_cache_status '
                   'time=${torblock_lookup_time}ms';
    
    access_log /var/log/nginx/performance.log perf;
}

Security-Focused Configuration

http {
    # High-security configuration
    torblock on;
    torblock_cache_size 10m;
    torblock_update_interval 300000;   # 5 minutes
    torblock_debug on;                 # Enable debug logging
    
    # Security logging
    log_format security '$remote_addr [$time_local] '
                       '"$request" $status '
                       'tor_status="$torblock_status" '
                       'exit_node="$torblock_exit_node" '
                       'user_agent="$http_user_agent"';
    
    server {
        listen 443 ssl;
        server_name secure.example.com;
        
        # Default: block all Tor
        torblock_action 444;  # Drop connection
        
        # Security-sensitive areas
        location /admin {
            torblock on;
            torblock_action 444;
            access_log /var/log/nginx/security-admin.log security;
        }
        
        location /api {
            torblock on;
            torblock_action 403;
            access_log /var/log/nginx/security-api.log security;
        }
    }
}

Mixed Policy Configuration

http {
    torblock on;
    torblock_cache_size 20m;
    
    # Global redirect URL
    torblock_redirect_url "/tor-information";
    
    server {
        listen 80;
        server_name blog.example.com;
        
        # Allow Tor for blog content
        torblock off;
        
        location /admin {
            # Block admin access
            torblock on;
            torblock_action 403;
        }
    }
    
    server {
        listen 80;
        server_name shop.example.com;
        
        # Allow browsing with notification
        location / {
            torblock on;
            torblock_action log;
        }
        
        # Block checkout process
        location /checkout {
            torblock on;
            torblock_action redirect;
            torblock_redirect_url "/checkout-tor-notice";
        }
        
        # Completely block payment
        location /payment {
            torblock on;
            torblock_action 444;
        }
    }
}

Error Handling

Configuration Validation

The module validates all directive values during configuration loading:

# Valid configurations
http {
    torblock on;                          # ✓ Valid
    torblock_action 403;                  # ✓ Valid
    torblock_cache_size 10m;              # ✓ Valid
    torblock_update_interval 3600000;     # ✓ Valid
}

# Invalid configurations that will cause errors
http {
    torblock maybe;                       # ✗ Invalid value
    torblock_action 999;                  # ✗ Invalid action
    torblock_cache_size -5m;              # ✗ Invalid size
    torblock_update_interval -1;          # ✗ Invalid interval
}

Runtime Error Handling

http {
    # Configure error handling
    torblock on;
    torblock_timeout 30000;
    
    # What happens when exit list can't be fetched:
    # - Existing cache entries remain valid
    # - New IPs are treated as "unknown"
    # - Error logged to error_log
    
    error_log /var/log/nginx/torblock-errors.log;
}

Context Hierarchy

Understanding how directives inherit and override:

http {
    # HTTP context - global defaults
    torblock on;                    # Global: ON
    torblock_action 403;            # Global: 403
    torblock_cache_size 10m;        # Only valid in http context
    
    server {
        # SERVER context - inherits from http
        # torblock: ON (inherited)
        # torblock_action: 403 (inherited)
        
        server_name site1.example.com;
        torblock_action redirect;    # Override: redirect
        torblock_redirect_url "/notice";
        
        location / {
            # LOCATION context - inherits from server
            # torblock: ON (inherited)
            # torblock_action: redirect (inherited from server)
        }
        
        location /public {
            # LOCATION context - override inheritance
            torblock off;            # Override: OFF
            # torblock_action: N/A (torblock is off)
        }
        
        location /admin {
            # LOCATION context - another override
            torblock on;             # Explicit: ON
            torblock_action 444;     # Override: 444
        }
    }
    
    server {
        # Another SERVER context
        server_name site2.example.com;
        # torblock: ON (inherited from http)
        # torblock_action: 403 (inherited from http)
        
        location / {
            # Uses http-level defaults
        }
    }
}

Performance Considerations

Memory Usage

# Cache size affects memory usage
http {
    # Small cache: ~1000 IPs, ~64KB memory
    torblock_cache_size 1m;
    
    # Medium cache: ~10000 IPs, ~640KB memory  
    torblock_cache_size 10m;
    
    # Large cache: ~100000 IPs, ~6.4MB memory
    torblock_cache_size 100m;
}

Update Frequency

# Balance between security and performance
http {
    # High security, more CPU usage
    torblock_update_interval 300000;   # 5 minutes
    
    # Balanced approach
    torblock_update_interval 1800000;  # 30 minutes
    
    # Performance focused, less current data
    torblock_update_interval 21600000; # 6 hours
}

Troubleshooting Configuration

Debug Configuration

http {
    # Enable comprehensive debugging
    torblock_debug on;
    error_log /var/log/nginx/debug.log debug;
    
    # Test endpoint for configuration verification
    server {
        listen 8080;
        location /torblock-test {
            add_header Content-Type application/json always;
            return 200 '{
                "torblock_status": "$torblock_status",
                "cache_status": "$torblock_cache_status",
                "lookup_time": "$torblock_lookup_time",
                "exit_node": "$torblock_exit_node"
            }';
        }
    }
}

Configuration Validation

# Test configuration syntax
nginx -t

# Test specific configuration file
nginx -t -c /path/to/nginx.conf

# Show parsed configuration
nginx -T | grep torblock

Next Steps

After reviewing the configuration reference:

  1. Context Hierarchy: Understand inheritance with Context Hierarchy
  2. Testing: Validate your configuration using Testing Procedures
  3. Troubleshooting: Debug issues with Troubleshooting Guide
  4. Performance: Optimize settings with Performance Tuning
Clone this wiki locally