Running a Tor Bridge on Linux: Complete obfs4 & WebTunnel Guide

In 2026, over 2.5 million people use the Tor network every single day to access the free and open internet. Journalists in authoritarian regimes, activists organizing protests, whistleblowers exposing corruption, and ordinary citizens protecting their privacy — all of them depend on a network that is entirely volunteer-operated.

The problem? There are only about 2,000 bridges serving those millions of users. Bridges are the most critical and scarce resource in the Tor ecosystem — they’re the first point of contact for users in censored countries, and every new bridge directly helps someone access information freely.

This guide will teach you everything you need to know about the Tor network, onion routing, and how to set up a production-ready obfs4 + WebTunnel bridge on Linux — complete with Nginx camouflage, firewall hardening, Prometheus monitoring, and CrowdSec integration.

The Tor Network: A Primer

What is Tor?

Tor (The Onion Router) is a decentralized, volunteer-operated network designed to protect users’ privacy and resist censorship. When you use Tor, your internet traffic is routed through a series of encrypted relays, making it extremely difficult for anyone — your ISP, government, or a malicious actor — to trace your activity back to you.

But Tor isn’t just a privacy tool. It’s an essential piece of human rights infrastructure. In countries like China, Iran, Russia, and Myanmar, where governments actively block access to information, Tor is often the only way for citizens to reach the uncensored internet.

A Brief History

The origins of Tor trace back to the 1990s at the U.S. Naval Research Laboratory (NRL), where researchers Paul Syverson, David Goldschlag, and Michael Reed developed the concept of onion routing — a technique for anonymous communication over a computer network. You can read more about Tor’s full history on the official site.

1. 1995 Milestone Onion Routing Invented

   Syverson, Goldschlag, and Reed at the U.S. Naval Research Laboratory develop the concept of layered encryption for anonymous communication.

2. 2002 Standard Tor Project Launched

   Roger Dingledine and Nick Mathewson (MIT graduates) join Syverson to build 'The Onion Router' — Tor. The code is released as open-source with about a dozen volunteer nodes.

3. 2004 Standard EFF Begins Funding

   The Electronic Frontier Foundation recognizes Tor's importance for digital rights and provides critical early funding. NRL releases the code to the public domain.

4. 2006 Milestone Tor Project, Inc. Founded

   The Tor Project becomes a 501(c)(3) nonprofit organization based in Massachusetts, ensuring long-term development and governance.

5. 2007 Standard Bridges Introduced

   Secret relay addresses (bridges) are developed to help users bypass firewalls in censored countries where the Tor directory is blocked.

6. 2008 Standard Tor Browser Development Begins

   A dedicated browser that packages Tor into an easy-to-use application, dramatically lowering the barrier to entry for non-technical users.

7. 2011 Milestone Arab Spring

   Tor plays a critical role as activists in Tunisia, Egypt, Libya, and Syria use it to organize protests and communicate securely despite government censorship.

8. 2013 Deprecated Snowden Revelations

   Edward Snowden's disclosures about global mass surveillance programs drive a massive surge in Tor adoption worldwide.

9. 2023 Standard WebTunnel Released

   A new pluggable transport that disguises Tor traffic as ordinary HTTPS, making it nearly impossible to block without collateral damage.

10. 2026 Today

    ~8,000 relays, ~2,000 bridges, and 2.5+ million daily users across 200+ countries. The network is entirely volunteer-operated.

How Onion Routing Works

Onion routing derives its name from the layers of an onion — your data is wrapped in multiple layers of encryption, and each relay in the circuit “peels off” one layer to reveal the next destination. No single relay ever knows both the origin and the destination of the traffic.

Here’s what makes this secure:

Key technical details of Tor’s circuit construction (see also the system overview in the Tor specification):

• Circuit path selection: The client randomly selects relays, avoiding two relays in the same /16 subnet or country for diversity.
• Key exchange: Each hop uses an ntor handshake (based on Curve25519) to establish a shared secret, providing perfect forward secrecy.
• Fixed-size cells: All data inside Tor is transmitted in 512-byte cells, preventing traffic analysis based on packet size.
• Circuit rotation: Circuits are rotated approximately every 10 minutes to limit the window for traffic correlation attacks.
• Directory authorities: Nine trusted servers maintain consensus about the network state, relay keys, and flags.

The Tor Ecosystem: Types of Volunteers

The Tor network is made up of different types of volunteer-operated nodes, each serving a distinct purpose:

Understanding Pluggable Transports

Censors don’t just block Tor by IP — they use Deep Packet Inspection (DPI) to identify and block the Tor protocol itself. Pluggable transports solve this by disguising Tor traffic as something else entirely.

In this guide, we’ll set up both obfs4 and WebTunnel on the same server — maximizing your impact with a single machine.

Prerequisites

Step 1: Install Tor from the Official Repository

Step 2: Install WebTunnel (Optional but Recommended)

WebTunnel is a newer pluggable transport that disguises Tor connections as regular HTTPS traffic. Unlike obfs4 (which looks like random data), WebTunnel actually uses WebSocket upgrades over HTTPS, making it nearly indistinguishable from legitimate web browsing. The Tor Project provides official setup instructions and a guide for building from source.

Step 3: Configure the Tor Bridge

Now for the main configuration. The torrc file controls all of Tor’s behavior.

Replace the contents of /etc/tor/torrc with:

# =============================================================
# Tor Bridge Configuration — obfs4 + WebTunnel
# =============================================================

# --- General Settings ---
SocksPort 0                        # Not a client — disable SOCKS
RunAsDaemon 0                      # Managed by systemd
DataDirectory /var/lib/tor
Log notice file /var/log/tor/notices.log
Log notice syslog

# --- Security Hardening ---
DisableDebuggerAttachment 1        # Prevent ptrace/debugger attachment

# --- Bridge Mode ---
BridgeRelay 1                      # This is a bridge, not a relay
PublishServerDescriptor bridge     # Publish to BridgeDB (not public directory)

# --- ORPort — IPv4 (NAT from router) + IPv6 (direct, global) ---
# IMPORTANT: Use 0.0.0.0 for NAT environments, not 127.0.0.1
ORPort 0.0.0.0:9001
ORPort [YOUR_IPV6_ADDRESS]:9001
ExtORPort auto

# --- Contact & Identity ---
ContactInfo your-email<at>example<dot>com
Nickname YourBridgeName

# --- obfs4 Transport ---
# Port 4443 must be forwarded from your router
ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
ServerTransportListenAddr obfs4 0.0.0.0:4443

# --- WebTunnel Transport ---
# Listens locally; Nginx reverse-proxies HTTPS to it
ServerTransportPlugin webtunnel exec /usr/local/bin/webtunnel-server
ServerTransportListenAddr webtunnel 127.0.0.1:15000
ServerTransportOptions webtunnel url=https://YOUR-DOMAIN/YOUR-SECRET-PATH

# --- Bandwidth Limits ---
# Adjust to what your connection can sustain (example: 250 Mbps)
RelayBandwidthRate 31 MBytes       # Sustained rate
RelayBandwidthBurst 35 MBytes     # Burst allowance

# --- Memory — cap internal queue memory (OOM protection) ---
MaxMemInQueues 4096 MB

# --- Statistics ---
ConnDirectionStatistics 1          # Enable connection direction stats

# --- DoS Protection ---
DoSRefuseSingleHopClientRendezvous 1

# --- Monitoring: Prometheus Metrics ---
MetricsPort 0.0.0.0:9052
MetricsPortPolicy accept 192.168.0.0/16
MetricsPortPolicy accept 127.0.0.0/8

# --- Control Port (for Nyx monitoring tool) ---
ControlPort 9051
CookieAuthentication 1

Let’s break down the critical sections:

Generate a WebTunnel Secret Path

The WebTunnel transport uses a secret URL path that acts as an authentication token. Generate a random 24-character string:

7Zkw18j2NWGK9X7PiiPUQRJB

Use this value in two places:

1. The torrc: ServerTransportOptions webtunnel url=https://your-domain.com/YOUR_SECRET
2. The Nginx config: location = /YOUR_SECRET

Step 4: Configure Nginx for WebTunnel Camouflage

The beauty of WebTunnel is that your server looks like a completely normal website. Visitors see a regular HTML page; only those who know the secret path can connect to the Tor bridge. This is called camouflage or domain fronting.

HTTP/1.1 200 OK
Content-Type: text/html
<html>Welcome...</html>

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
[Tor traffic flows through the tunnel]

Step 5: Configure Port Forwarding

If your server is behind a router (common in home setups), you need to forward the following ports from your router’s public IP to your server’s local IP:

The exact steps depend on your router. Here’s the general process:

Server Firewall (UFW)

If you’re using UFW (Uncomplicated Firewall) on your server:

If using iptables directly:

IPv6: No NAT Needed

Unlike IPv4, IPv6 addresses are globally routable — there is no NAT. This means your server’s IPv6 address is directly reachable from the internet without port forwarding. However, you still need to:

1. Allow the ports in your server’s firewall (UFW handles both IPv4 and IPv6 automatically)
2. Allow the ports in your router’s IPv6 firewall — most routers have a separate IPv6 firewall that blocks all incoming traffic by default

Step 6: AppArmor Configuration

On Debian/Ubuntu systems, AppArmor may restrict what Tor and obfs4proxy can do. You need to ensure the obfs4proxy profile allows execution:

Step 7: Start and Verify

Verify External Reachability

From a different machine (or using an online port checker), verify that your ports are accessible:

Step 8: Monitoring with Prometheus and Grafana

Tor exposes a rich set of metrics via its MetricsPort in Prometheus format. These metrics let you monitor bandwidth usage, connections, circuit building, and relay health in real time.

Configure Prometheus Scraping

Add a scrape target for your Tor bridge in your Prometheus configuration:

scrape_configs:
  - job_name: 'tor-bridge'
    scrape_interval: 30s
    scrape_timeout: 10s
    metrics_path: '/metrics'
    static_configs:
      - targets: ['YOUR_SERVER_IP:9052']
        labels:
          instance: 'tor-bridge'
          nickname: 'YourBridgeName'

Key Metrics to Monitor

Tor exposes dozens of Prometheus metrics. Here are the most important ones for a bridge operator:

Grafana Dashboard

You can build a comprehensive Grafana dashboard with panels for:

1. Bandwidth — rate(tor_relay_traffic_bytes[5m]) — real-time throughput in/out
2. Connections — tor_relay_connections_total by type — who’s connecting
3. Relay Flags — tor_relay_flag — has the network recognized your bridge?
4. Circuits — tor_relay_circuits_total — how many circuits are active
5. System Resources — process_resident_memory_bytes, process_cpu_seconds_total
6. Health — tor_relay_load_oom_bytes_total, tor_relay_load_tcp_exhaustion_total

Nyx: Terminal-Based Monitoring

Nyx is a terminal UI for monitoring Tor in real time. It connects to the ControlPort and shows bandwidth graphs, connections, circuits, and configuration.

Step 9: CrowdSec Integration (If Applicable)

If you run CrowdSec on the same server (common when running Nginx), you’ll face a challenge: CrowdSec is designed to block malicious IPs, but Tor bridge clients may trigger false positives. Legitimate Tor users connecting to your bridge could get blocked by your own IDS.

The solution is a three-layer bypass that ensures Tor traffic is never blocked:

Layer 1: iptables — Bypass the Firewall Bouncer

Insert ACCEPT rules for Tor-specific ports before the CROWDSEC_CHAIN:

Layer 2: Nginx — Bypass the Lua Bouncer

If your CrowdSec Nginx bouncer uses a rewrite_by_lua_block at the http {} level, add an exception for your Tor domain:

rewrite_by_lua_block {
    local cs = require "plugins.crowdsec.lib.crowdsec"

    -- Bypass CrowdSec for Tor bridge domain
    if ngx.var.host == "your-tor-domain.com" then
        -- Skip CrowdSec check entirely for Tor bridge traffic
    else
        local ok, err = cs.Allow(ngx.var.remote_addr)
        if not ok then
            ngx.exit(ngx.HTTP_CLOSE)
        end
    end
}

Layer 3: CrowdSec Parser Whitelist

Even with the above, CrowdSec will still parse your Tor logs and may create local decisions. Create a parser whitelist so it ignores all traffic to your Tor domain:

name: custom/tor-bridge-whitelist
description: "Ignore all traffic to the Tor bridge domain"
whitelist:
  reason: "Tor bridge traffic — legitimate by definition"
  expression:
    - evt.Parsed.target_fqdn == 'your-tor-domain.com'

For CrowdSec to detect the target_fqdn, your Nginx logs must include the $host variable. Create a custom log format:

# Log format with vhost prefix for CrowdSec target_fqdn detection
log_format combined_vhost
    '$host $remote_addr - $remote_user [$time_local] '
    '"$request" $status $body_bytes_sent '
    '"$http_referer" "$http_user_agent"';

Then use it in your Tor server block:

access_log /var/log/nginx/tor.access.log combined_vhost;

After making changes, reload both services:

Persist iptables Rules Across Reboots

The iptables bypass rules would be lost on reboot. Create a systemd service to re-apply them:

[Unit]
Description=Tor Bridge — iptables bypass for CrowdSec
After=crowdsec-firewall-bouncer.service
Wants=crowdsec-firewall-bouncer.service

[Service]
Type=oneshot
RemainAfterExit=yes

# IPv4: Accept Tor traffic before CROWDSEC_CHAIN
ExecStart=/bin/sh -c '\
  iptables  -C INPUT -p tcp --dport 4443 -j ACCEPT 2>/dev/null || \
  iptables  -I INPUT 1 -p tcp --dport 4443 -j ACCEPT; \
  iptables  -C INPUT -p tcp --dport 9001 -j ACCEPT 2>/dev/null || \
  iptables  -I INPUT 1 -p tcp --dport 9001 -j ACCEPT'

# IPv6: Same rules
ExecStart=/bin/sh -c '\
  ip6tables -C INPUT -p tcp --dport 4443 -j ACCEPT 2>/dev/null || \
  ip6tables -I INPUT 1 -p tcp --dport 4443 -j ACCEPT; \
  ip6tables -C INPUT -p tcp --dport 9001 -j ACCEPT 2>/dev/null || \
  ip6tables -I INPUT 1 -p tcp --dport 9001 -j ACCEPT'

[Install]
WantedBy=multi-user.target

Architecture Overview

Here’s the complete architecture of what you’ve built:

Verification Checklist

After everything is set up, run through this checklist to confirm your bridge is fully operational:

Operational Notes

What Happens After You Start

1. 0–1 hour Standard Bootstrap & Self-Test

   Tor connects to the network, downloads the consensus, and tests if your ORPort is reachable. If the self-test passes, your bridge is operational.

2. 1–24 hours Descriptor Publication

   Tor publishes your bridge descriptor to the Bridge Authority. Your bridge becomes known to BridgeDB but is not yet distributed to users.

3. 24–48 hours Standard BridgeDB Distribution

   BridgeDB starts distributing your bridge line to users who request bridges. You may start seeing your first client connections.

4. 1–7 days Flag Accumulation

   Directory authorities assign flags based on your bridge's behavior. 'Running' and 'Valid' come first; 'Stable' requires ~7 days of continuous uptime.

5. Ongoing Milestone Steady State

   Your bridge is fully integrated into the Tor network. Monitor metrics, keep software updated, and maintain uptime for maximum impact.

Maintenance Best Practices

Backup Critical Files

These files contain your bridge’s identity. Losing them means starting over with a new fingerprint:

Troubleshooting

sudo aa-status | grep obfs4

ls -la /var/lib/tor/pt_state/

The Network Needs You

Running a Tor bridge is one of the most impactful things you can do for internet freedom. Every bridge you operate is a direct lifeline for people under censorship — journalists in Iran, activists in China, students in Russia, citizens in Myanmar. The technical barrier is modest; the human impact is immeasurable.

If you found this guide helpful, consider sharing it with others who might want to contribute. The more bridges we have, the harder it is for censors to block access to the free internet.

And if you want to go further: set up a dedicated server for exit relays — they’re the most scarce and impactful resource in the entire Tor network. That’s a guide for another day.

Further Reading & Resources

Tor networkwww.torproject.org

Toren.wikipedia.org

origins of Torwww.onion-router.net

Paul Syversonen.wikipedia.org

onion routingen.wikipedia.org

Tor's full historywww.torproject.org

circuit constructionspec.torproject.org

system overviewtpo.pages.torproject.net

Tor network has roughly **8,000 relays** but only about **2,000 bridges**metrics.torproject.org

Pluggable transportsarxiv.org

obfs4gitlab.torproject.org

WebTunnelgitlab.torproject.org

Snowflake browser extensionsnowflake.torproject.org

Debian/Ubuntu repositorycommunity.torproject.org

official setup instructionscommunity.torproject.org

building from sourcecommunity.torproject.org

Nyxnyx.torproject.org

CrowdSecwww.crowdsec.net

Tor Metrics Relay Searchmetrics.torproject.org