This is a personal project page. Nothing to see here.
EOF ``` 2. **Obtain a TLS certificate** (if you don't already have one) **Obtain Let's Encrypt certificate** ```bash sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com ``` 3. **Create the Nginx server block** **File: `/etc/nginx/sites-available/tor-bridge.conf`** ```nginx # Tor WebTunnel Bridge — Camouflage configuration # This looks like a normal HTTPS website but proxies # a secret path to the WebTunnel pluggable transport server { listen 443 ssl; listen [::]:443 ssl; http2 on; server_name your-domain.com; # TLS certificates ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # === Normal website (camouflage) === root /var/www/tor-camouflage; index index.html; location / { try_files $uri $uri/ =404; } # === WebTunnel reverse proxy (secret path) === # Replace YOUR_SECRET_PATH with your generated secret location = /YOUR_SECRET_PATH { proxy_pass http://127.0.0.1:15000; proxy_http_version 1.1; # WebSocket upgrade headers (required for WebTunnel) proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # Standard proxy headers proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Accept-Encoding ""; add_header Front-End-Https on; proxy_redirect off; proxy_buffering off; proxy_request_buffering off; # Long timeout for persistent Tor connections proxy_read_timeout 36000s; proxy_send_timeout 36000s; # Disable logging for the secret path (privacy) access_log off; error_log off; } } # HTTP to HTTPS redirect server { listen 80; listen [::]:80; server_name your-domain.com; return 301 https://$host$request_uri; } ``` 4. **Enable the site and test** **Enable Nginx site and test configuration** ```bash sudo ln -sf /etc/nginx/sites-available/tor-bridge.conf \ /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx ``` **Comparison: What censors see vs What actually happens** **What censors see** **Normal HTTPS website** A `GET /` request to your domain returns a plain HTML page. DPI sees standard TLS 1.3 traffic to a registered domain. Nothing suspicious. ``` HTTP/1.1 200 OK Content-Type: text/html Welcome... ``` **What actually happens** **WebTunnel bridge connection** A `GET /SECRET_PATH` with a `Connection: Upgrade` header reaches the WebTunnel server, which establishes a persistent tunnel for Tor traffic — all inside the same TLS session. ``` 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: **Required Port Forwards** | Port | Protocol | Purpose | Required? | | --- | --- | --- | --- | | **9001** | TCP | ORPort — relay-to-relay communication | Yes (always) | | **4443** | TCP | obfs4 — obfuscated transport | Yes (if running obfs4) | | **443** | TCP | HTTPS — WebTunnel via Nginx | Yes (if running WebTunnel) | The exact steps depend on your router. Here's the general process: **Generic Router Port Forwarding** 1. **Access your router's admin panel** (usually at `192.168.0.1` or `192.168.1.1`) 2. **Find the port forwarding section** (often under "NAT", "Firewall", or "Port Forwarding") 3. **Create rules for each port:** - **External port**: 9001 → **Internal IP**: your server's LAN IP → **Internal port**: 9001 - **External port**: 4443 → **Internal IP**: your server's LAN IP → **Internal port**: 4443 - **External port**: 443 → **Internal IP**: your server's LAN IP → **Internal port**: 443 (if not already forwarded) 4. **Save and apply** the changes ### Server Firewall (UFW) If you're using UFW (Uncomplicated Firewall) on your server: **Configure UFW for Tor bridge ports** ```bash sudo ufw allow 9001/tcp comment "Tor ORPort" sudo ufw allow 4443/tcp comment "Tor obfs4 Bridge" # Port 443 is likely already open if you run Nginx sudo ufw allow 443/tcp comment "HTTPS" sudo ufw reload ``` If using `iptables` directly: **Configure iptables for Tor bridge ports** ```bash sudo iptables -A INPUT -p tcp --dport 9001 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 4443 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT ``` ### 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 **Warning — Router IPv6 Firewall** Most routers **block all inbound IPv6** by default (unlike IPv4 where only NAT provides the "firewall"). You need to create explicit **allow rules** in your router's IPv6 firewall for TCP ports 9001 and 4443 to reach your server's IPv6 address. No destination NAT is needed — just firewall accept rules. **Verify IPv6 firewall rules** ```bash # Verify your server's IPv6 address ip -6 addr show scope global | grep inet6 # Verify IPv6 firewall rules on the server sudo ip6tables -L INPUT -n | grep -E "9001|4443" # Test IPv6 reachability from another machine nc -6zv YOUR_IPV6_ADDRESS 9001 ``` --- ## 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: **Configure AppArmor for obfs4proxy** ```bash # Check if the profile exists sudo aa-status 2>/dev/null | grep obfs4proxy # If restricted, set to complain mode sudo aa-complain /usr/bin/obfs4proxy 2>/dev/null # Or create an explicit allow rule echo "/usr/bin/obfs4proxy mr," | sudo tee -a /etc/apparmor.d/local/system_tor sudo apparmor_parser -r /etc/apparmor.d/system_tor ``` --- ## Step 7: Start and Verify **Launch the Bridge** 1. **Start Tor** **Restart Tor service** ```bash sudo systemctl restart tor ``` 2. **Check the logs for successful bootstrap** **Watch Tor bootstrap process** ```bash sudo journalctl -u tor -f --no-pager | head -30 ``` Look for these key messages: **Successful bootstrap output** ```text Bootstrapped 0% (starting): Starting Bootstrapped 5% (conn): Connecting to a relay Bootstrapped 10% (conn_done): Connected to a relay Bootstrapped 14% (handshake): Handshaking with a relay Bootstrapped 15% (handshake_done): Handshake with a relay done Bootstrapped 75% (enough_dirinfo): Loaded enough directory info to build circuits Bootstrapped 90% (ap_handshake_done): Handshake finished with a relay to build circuits Bootstrapped 95% (circuit_create): Establishing a Tor circuit Bootstrapped 100% (done): Done Self-testing indicates your ORPort 86.x.x.x:9001 is reachable from the outside. Excellent. Registered server transport 'obfs4' at '0.0.0.0:4443' Registered server transport 'webtunnel' at '127.0.0.1:15000' ``` 3. **Verify all three processes are running** **Check that Tor, obfs4proxy, and webtunnel-server are running** ```bash ps aux | grep -E "(tor|obfs4|webtunnel)" | grep -v grep ``` You should see three processes: `tor`, `obfs4proxy`, and `webtunnel-server`. 4. **Verify all ports are listening** **Check listening ports for Tor bridge** ```bash ss -tlnp | grep -E "(:443|9001|4443|15000|9051|9052)" ``` **Output — Expected listening ports** ```text LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=...,fd=...)) LISTEN 0 4096 0.0.0.0:9001 0.0.0.0:* users:(("tor",pid=...,fd=...)) LISTEN 0 4096 0.0.0.0:4443 0.0.0.0:* users:(("obfs4proxy",pid=...,fd=...)) LISTEN 0 4096 127.0.0.1:15000 0.0.0.0:* users:(("webtunnel-ser",pid=...,fd=...)) LISTEN 0 4096 127.0.0.1:9051 0.0.0.0:* users:(("tor",pid=...,fd=...)) LISTEN 0 4096 0.0.0.0:9052 0.0.0.0:* users:(("tor",pid=...,fd=...)) ``` 5. **Retrieve your bridge fingerprint** **Get bridge fingerprint** ```bash cat /var/lib/tor/fingerprint ``` ### Verify External Reachability From a different machine (or using an online port checker), verify that your ports are accessible: **Test ORPort reachability from another machine** ```bash # From another machine: nc -zv YOUR_PUBLIC_IP 9001 nc -zv YOUR_PUBLIC_IP 4443 curl -I https://your-domain.com/ ``` **Tip — The ORPort Self-Test** Tor performs its own reachability test during bootstrap. If you see `Self-testing indicates your ORPort is reachable from the outside`, you're good. If the self-test fails, double-check your port forwarding rules and firewall configuration. --- ## 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: **File: `prometheus.yml` (snippet)** ```yaml 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' ``` **Info — Firewall for Metrics Port** The MetricsPort (9052) should **only** be accessible from your monitoring server, not the public internet. Use `MetricsPortPolicy accept YOUR_MONITORING_IP/32` in `torrc` and restrict access via firewall: **Restrict MetricsPort to monitoring server** ```bash sudo ufw allow from YOUR_MONITORING_IP to any port 9052 proto tcp \ comment "Prometheus: Tor Bridge Metrics" ``` ### Key Metrics to Monitor Tor exposes dozens of Prometheus metrics. Here are the most important ones for a bridge operator: **Essential Tor Prometheus Metrics** | Metric | Type | What It Tells You | | --- | --- | --- | | `tor_relay_connections_total` | Counter | Total connections by type and direction (inbound/outbound, OR/directory) | | `tor_relay_traffic_bytes` | Counter | Total bytes read/written — your bandwidth contribution to the network | | `tor_relay_flag` | Gauge | Directory flags assigned to your relay (Stable, Running, Valid, etc.) | | `tor_relay_circuits_total` | Gauge | Number of active circuits by state (opened, closed, etc.) | | `tor_relay_streams_total` | Counter | Streams processed — a proxy for actual user connections | | `tor_relay_load_oom_bytes_total` | Counter | Out-of-memory events — if this increases, add more RAM | | `tor_relay_load_tcp_exhaustion_total` | Counter | TCP port exhaustion — if this increases, tune kernel network settings | | `process_resident_memory_bytes` | Gauge | Current RAM usage of the Tor process | | `process_cpu_seconds_total` | Counter | CPU time consumed by Tor | ### 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` **Tip — Relay Flags Timeline** After starting your bridge, relay flags will appear gradually: - **Running**: ~1 hour after starting - **Valid**: ~1 hour - **Stable**: ~7 days of continuous uptime - **Guard**: ~8 days (if applicable) Be patient — the Tor directory authorities take time to trust new relays. Keep your bridge running consistently and the flags will come. ### Nyx: Terminal-Based Monitoring [Nyx](https://nyx.torproject.org/) is a terminal UI for monitoring Tor in real time. It connects to the ControlPort and shows bandwidth graphs, connections, circuits, and configuration. **Install and run Nyx** ```bash sudo apt install -y nyx sudo -u debian-tor nyx ``` --- ## Step 9: CrowdSec Integration (If Applicable) If you run [CrowdSec](https://www.crowdsec.net/) 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. **Warning — The Problem** CrowdSec's firewall bouncer adds a `CROWDSEC_CHAIN` at the top of your iptables INPUT chain, and the Nginx bouncer checks every request against a blocklist. Both can inadvertently block legitimate Tor bridge clients. 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: **Add iptables bypass rules for Tor ports** ```bash # IPv4 sudo iptables -I INPUT 1 -p tcp --dport 4443 -j ACCEPT # obfs4 sudo iptables -I INPUT 1 -p tcp --dport 9001 -j ACCEPT # ORPort # IPv6 sudo ip6tables -I INPUT 1 -p tcp --dport 4443 -j ACCEPT sudo ip6tables -I INPUT 1 -p tcp --dport 9001 -j ACCEPT ``` **Info — Why Not Port 443?** Port 443 is shared with all your HTTPS services, not just Tor. Bypassing CrowdSec for **all** HTTPS traffic would create a security hole. Instead, the WebTunnel bypass for port 443 is handled at the Nginx level (Layer 2), where we can filter by domain name. ### 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: **File: `/etc/nginx/conf.d/crowdsec_nginx.conf` (modified section)** ```lua 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: **File: `/etc/crowdsec/parsers/s02-enrich/tor-bridge-whitelist.yaml`** ```yaml 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: **File: `/etc/nginx/conf.d/tor_log_format.conf`** ```nginx # 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: ```nginx access_log /var/log/nginx/tor.access.log combined_vhost; ``` After making changes, reload both services: **Reload CrowdSec and Nginx** ```bash sudo systemctl reload crowdsec sudo systemctl reload nginx ``` ### Persist iptables Rules Across Reboots The iptables bypass rules would be lost on reboot. Create a systemd service to re-apply them: **File: `/etc/systemd/system/tor-bypass-crowdsec.service`** ```ini [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 ``` **Enable the iptables persistence service** ```bash sudo systemctl daemon-reload sudo systemctl enable --now tor-bypass-crowdsec.service ``` --- ## How do the bridge's components fit together? The bridge is one Tor process reachable through two pluggable transports, obfs4 and WebTunnel, which the router exposes with IPv4 port forwards and IPv6 firewall rules while CrowdSec bypass rules keep those ports open; both transports hand their connections to Tor over ExtORPort, Tor talks outbound to the network, and Prometheus scrapes the MetricsPort that Grafana draws from. Here's the complete architecture of what you've built: **Complete Tor Bridge Architecture (Dual-Stack IPv4 + IPv6)** ```mermaid flowchart TB subgraph Internet["🌍 Censored Users"] User1["Tor Client