Installation Guide

Installation Guide

This guide provides detailed instructions for installing the nginx-torblocker module on various systems.

Prerequisites

Before installing the module, ensure you have the following:

System Requirements

• Operating System: Linux (Ubuntu 18.04+, CentOS 7+, Debian 9+)
• Nginx: Version 1.18.0 or later (installed and running)
• Compiler: GCC or compatible C compiler
• Memory: At least 512MB available RAM
• Network: Internet access for downloading sources and Tor lists

Required Packages

Ubuntu/Debian

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

CentOS/RHEL/Fedora

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

Alpine Linux

apk add --no-cache build-base gcc wget curl
apk add --no-cache pcre-dev zlib-dev openssl-dev

Step 1: Check Your Nginx Version

First, determine your exact Nginx version:

nginx -v

Example output:

nginx version: nginx/1.26.0

Important: The module must be built against the exact same version of Nginx you're running.

Step 2: Download Nginx Source Code

Download the source code matching your Nginx version:

# Create a temporary build directory
mkdir -p ~/nginx-build && cd ~/nginx-build

# Download the matching Nginx source (replace 1.26.0 with your version)
NGINX_VERSION=$(nginx -v 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+')
wget https://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz

# Extract the source
tar xzf nginx-${NGINX_VERSION}.tar.gz

Step 3: Clone the Module Repository

# Clone the nginx-torblocker repository
git clone https://github.com/RumenDamyanov/nginx-torblocker.git
cd nginx-torblocker

Step 4: Build the Module

# Enter the Nginx source directory
cd ~/nginx-build/nginx-${NGINX_VERSION}

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

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

Expected output:

make -f objs/Makefile modules
make[1]: Entering directory '/home/user/nginx-build/nginx-1.26.0'
cc -c -fPIC -pipe -O -W -Wall -Wpointer-arith -Wno-unused-parameter...
cc -o objs/ngx_http_torblocker_module.so ...
make[1]: Leaving directory '/home/user/nginx-build/nginx-1.26.0'

Step 5: Install the Module

Option A: Standard Installation

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

# Set proper permissions
sudo chmod 644 /usr/lib/nginx/modules/ngx_http_torblocker_module.so

Option B: Custom Installation

# Create custom modules directory
sudo mkdir -p /etc/nginx/modules

# Copy module
sudo cp objs/ngx_http_torblocker_module.so /etc/nginx/modules/

# Set permissions
sudo chmod 644 /etc/nginx/modules/ngx_http_torblocker_module.so

Step 6: Load the Module

Edit your main Nginx configuration file:

sudo nano /etc/nginx/nginx.conf

Add the following line at the very top of the file (before any other directives):

For Standard Installation:

load_module modules/ngx_http_torblocker_module.so;

For Custom Installation:

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

Complete example nginx.conf:

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 globally
    torblock on;
    
    server {
        listen 80;
        server_name example.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Step 7: Test the Configuration

Test the Nginx configuration syntax:

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 8: Restart Nginx

sudo systemctl restart nginx

# Or if using init.d
sudo service nginx restart

Step 9: Verify Installation

Check that Nginx is running and the module is loaded:

# Check Nginx status
sudo systemctl status nginx

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

# Test that the module is working
curl -I http://localhost

Verification Steps

1. Check Module Loading

sudo nginx -V 2>&1 | grep -o "configure arguments.*" | tr ' ' '\n' | grep module

2. Test Basic Functionality

# Check if Tor blocking is active (should see no errors)
echo "torblock on;" | sudo nginx -t -c /dev/stdin

3. Monitor Logs

# Watch for any module-related messages
sudo tail -f /var/log/nginx/error.log | grep -i tor

Platform-Specific Notes

Ubuntu 20.04/22.04

• Default Nginx modules directory: /usr/lib/nginx/modules/
• Service management: systemctl
• Configuration file: /etc/nginx/nginx.conf

CentOS 7/8

• Default Nginx modules directory: /usr/lib64/nginx/modules/
• Service management: systemctl (CentOS 7+) or service (CentOS 6)
• Configuration file: /etc/nginx/nginx.conf

Docker Environments

For Docker deployments, see the Docker Installation Guide.

Troubleshooting Installation

Common Issues

"Module not found" Error

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

Solutions:

1. Verify the file exists: ls -la /usr/lib/nginx/modules/ngx_http_torblocker_module.so
2. Check permissions: sudo chmod 644 /usr/lib/nginx/modules/ngx_http_torblocker_module.so
3. Ensure correct path in load_module directive

Version Mismatch Error

nginx: [emerg] module version 1024000 instead of 1026000

Solutions:

1. Rebuild the module against the correct Nginx version
2. Verify versions match: nginx -v vs build source version

Permission Denied

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

Solutions:

1. Check SELinux: sudo setsebool -P httpd_execmem 1
2. Fix file permissions: sudo chmod 644 /path/to/module.so
3. Check directory permissions: sudo chmod 755 /usr/lib/nginx/modules/

Next Steps

After successful installation:

1. Basic Configuration: See Basic Configuration Guide
2. Testing: Review Testing Procedures
3. Real-World Examples: Explore Usage Examples

Cleanup

Remove temporary build files:

cd ~
rm -rf ~/nginx-build

The module is now installed and ready for configuration!