Skip to content

Module Loading

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

Module Loading

This guide explains how to properly load the nginx-torblocker module in various Nginx configurations and environments.

Overview

The nginx-torblocker module is a dynamic module that must be loaded explicitly using the load_module directive. This guide covers different loading scenarios and best practices.

Basic Module Loading

Standard Loading

The load_module directive must be placed at the top level of your nginx.conf file, before any other configuration blocks:

# Must be at the very top of nginx.conf
load_module modules/ngx_http_torblocker_module.so;

# Then your configuration blocks
events {
    worker_connections 1024;
}

http {
    # Your HTTP configuration
}

Complete Example

# Load the module first
load_module modules/ngx_http_torblocker_module.so;

# Optional: Load other modules
load_module modules/ngx_http_geoip_module.so;
load_module modules/ngx_http_image_filter_module.so;

# Main configuration
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
    use epoll;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    # Now you can use torblock directives
    torblock on;
    
    # Include server configurations
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Module Path Configurations

Option 1: Relative Path (Recommended)

Use the relative path which works with standard Nginx installations:

load_module modules/ngx_http_torblocker_module.so;

This assumes the module is in Nginx's standard modules directory:

  • Ubuntu/Debian: /usr/lib/nginx/modules/
  • CentOS/RHEL: /usr/lib64/nginx/modules/
  • Custom builds: Relative to Nginx prefix

Option 2: Absolute Path

Use absolute path if you have a custom installation:

# Ubuntu/Debian
load_module /usr/lib/nginx/modules/ngx_http_torblocker_module.so;

# CentOS/RHEL
load_module /usr/lib64/nginx/modules/ngx_http_torblocker_module.so;

# Custom installation
load_module /opt/nginx/modules/ngx_http_torblocker_module.so;

Option 3: Custom Module Directory

If you store modules in a custom location:

load_module /etc/nginx/modules/ngx_http_torblocker_module.so;

Configuration File Organization

Single Configuration File

For simple setups, load the module in your main nginx.conf:

# /etc/nginx/nginx.conf
load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    torblock on;
    
    server {
        listen 80;
        server_name example.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Modular Configuration

For complex setups with multiple configuration files:

Main configuration (/etc/nginx/nginx.conf):

# Load all modules at the top
load_module modules/ngx_http_torblocker_module.so;
load_module modules/ngx_http_ssl_module.so;

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    # Global torblock settings
    include /etc/nginx/conf.d/torblock.conf;
    
    # Include site configurations
    include /etc/nginx/sites-enabled/*.conf;
}

Torblock configuration (/etc/nginx/conf.d/torblock.conf):

# Global Tor blocking configuration
torblock on;
torblock_update_interval 3600000;

# Logging configuration
log_format torblock '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   'torblock="$torblock_status"';

Site configuration (/etc/nginx/sites-enabled/example.conf):

server {
    listen 80;
    server_name example.com;
    
    access_log /var/log/nginx/example.log torblock;
    
    location / {
        root /var/www/example;
        index index.html;
    }
    
    location /admin {
        torblock on;  # Override global if needed
        root /var/www/admin;
    }
}

Platform-Specific Loading

Ubuntu/Debian with Package Manager

If Nginx was installed via apt:

# Standard path for apt-installed Nginx
load_module modules/ngx_http_torblocker_module.so;

Module should be copied to: /usr/lib/nginx/modules/

CentOS/RHEL with Package Manager

If Nginx was installed via yum/dnf:

# Standard path for yum-installed Nginx  
load_module modules/ngx_http_torblocker_module.so;

Module should be copied to: /usr/lib64/nginx/modules/

Docker Environments

For Docker containers:

Dockerfile:

FROM nginx:alpine

# Copy the module
COPY ngx_http_torblocker_module.so /usr/lib/nginx/modules/

# Copy configuration
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

nginx.conf:

load_module modules/ngx_http_torblocker_module.so;

events {
    worker_connections 1024;
}

http {
    torblock on;
    
    server {
        listen 80;
        server_name localhost;
        
        location / {
            root /usr/share/nginx/html;
            index index.html;
        }
    }
}

Custom Compiled Nginx

If you compiled Nginx from source:

# Check your Nginx prefix
nginx -V 2>&1 | grep -o '\--prefix=[^ ]*'

# Example output: --prefix=/usr/local/nginx

Then use the appropriate path:

# For prefix=/usr/local/nginx
load_module modules/ngx_http_torblocker_module.so;

# Module should be in: /usr/local/nginx/modules/

Verification and Testing

Check Module Path

Find where Nginx expects modules:

# Check Nginx configuration
nginx -V 2>&1 | grep -o '\--modules-path=[^ ]*'

# List current modules directory
ls -la $(nginx -V 2>&1 | grep -o '\--modules-path=[^ ]*' | cut -d= -f2)

# Alternative: Find the directory
find /usr -name "modules" -type d 2>/dev/null | grep nginx

Verify Module Loading

Test if the module loads correctly:

# Test configuration syntax
sudo nginx -t

# Expected success output:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

Check for Loading Errors

Monitor error logs during startup:

# Watch error log during reload
sudo tail -f /var/log/nginx/error.log &
sudo nginx -s reload

# Look for module-related messages
sudo grep -i "torblock\|module" /var/log/nginx/error.log

Verify Module Functionality

Test that directives are recognized:

# Create test configuration
echo "torblock on;" | sudo nginx -t -c /dev/stdin

# Should not show "unknown directive" error

Troubleshooting Module Loading

Error: "module not found"

nginx: [emerg] dlopen() "/usr/lib/nginx/modules/ngx_http_torblocker_module.so" failed (2: No such file or directory)

Solutions:

  1. Check if file exists:

    ls -la /usr/lib/nginx/modules/ngx_http_torblocker_module.so

  2. Find correct modules directory:

    find /usr -name "*.so" -path "*/nginx/modules/*" 2>/dev/null

  3. Copy module to correct location:

    sudo cp ngx_http_torblocker_module.so /usr/lib/nginx/modules/

Error: "module version mismatch"

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

Solutions:

  1. Check Nginx version:

    nginx -v

  2. Rebuild module against correct version:

    # Download matching Nginx source and rebuild
wget https://nginx.org/download/nginx-1.26.0.tar.gz
# Follow build instructions

Error: "unknown directive torblock"

nginx: [emerg] unknown directive "torblock" in /etc/nginx/nginx.conf:15

Solutions:

  1. Ensure load_module is first:

    # Must be at very top
load_module modules/ngx_http_torblocker_module.so;

events {
    # ...
}

  2. Check module path:

    sudo nginx -T | grep load_module

Error: "permission denied"

nginx: [emerg] dlopen() failed (13: Permission denied)

Solutions:

  1. Fix file permissions:

    sudo chmod 644 /usr/lib/nginx/modules/ngx_http_torblocker_module.so

  2. Check SELinux (CentOS/RHEL):

    sudo setsebool -P httpd_execmem 1

  3. Check directory permissions:

    sudo chmod 755 /usr/lib/nginx/modules/

Best Practices

1. Use Relative Paths

# Good: Works across different installations
load_module modules/ngx_http_torblocker_module.so;

# Avoid: Hard-coded absolute paths
load_module /usr/lib/nginx/modules/ngx_http_torblocker_module.so;

2. Group Module Loading

# Load all modules at the top
load_module modules/ngx_http_torblocker_module.so;
load_module modules/ngx_http_geoip_module.so;
load_module modules/ngx_http_realip_module.so;

# Then configuration
events {
    # ...
}

3. Comment Module Purpose

# Security modules
load_module modules/ngx_http_torblocker_module.so;  # Tor blocking
load_module modules/ngx_http_limit_req_module.so;   # Rate limiting

# Performance modules  
load_module modules/ngx_http_gzip_module.so;        # Compression

4. Environment-Specific Loading

Use environment variables for different deployments:

# Development
load_module modules/ngx_http_torblocker_module.so;

# Production might load additional security modules
load_module modules/ngx_http_torblocker_module.so;
load_module modules/ngx_http_modsecurity_module.so;

Integration with Configuration Management

Ansible Example

- name: Copy Tor blocker module
  copy:
    src: ngx_http_torblocker_module.so
    dest: /usr/lib/nginx/modules/
    mode: '0644'
    owner: root
    group: root

- name: Configure Nginx with Tor blocker
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: reload nginx

Docker Compose Example

version: '3.8'
services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./ngx_http_torblocker_module.so:/usr/lib/nginx/modules/ngx_http_torblocker_module.so:ro
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"

Next Steps

After successfully loading the module:

  1. Basic Setup: Continue with Basic Configuration
  2. Advanced Usage: Explore Advanced Configuration
  3. Troubleshooting: Review Troubleshooting Guide if needed
  4. Development: See Development Setup for building custom versions
Clone this wiki locally