tor-guard-relay/docs/MULTI-MODE.md

🔄 Multi-Mode Relay Guide - Tor Guard Relay

Complete guide to running Guard/Middle relays, Exit relays, and obfs4 Bridges.

---

Table of Contents

• Overview
• Mode Comparison
• Guard/Middle Relay Mode
• Exit Relay Mode
• obfs4 Bridge Mode
• Configuration Methods
• Environment Variables Reference
• Switching Modes
• Troubleshooting

---

Overview

The Tor Guard Relay container now supports three relay modes:

Mode	Purpose	Public Visibility	Legal Risk	Bandwidth Needs
Guard/Middle	Entry/routing relay	High	Low	Medium-High
Exit	Exit traffic to internet	High	HIGH	High
Bridge	Help censored users	Hidden	Low	Low-Medium

Key Features

• ✅ Dynamic Configuration - Generate config from environment variables
• ✅ obfs4 Support - Pluggable transport for bridges
• ✅ Backwards Compatible - Still supports mounting config files
• ✅ Secure Defaults - Guard/middle as default mode

---

Mode Comparison

Guard/Middle Relay (Default)

What it does:

• Acts as entry point (guard) or routing node (middle) in Tor circuits
• Does NOT handle exit traffic to the internet
• Published in the main Tor directory

Best for:

• Operators who want to contribute without legal complexity
• Stable, high-bandwidth connections
• Long-term operation (8+ days to earn Guard flag - requires at least 5 of 9 directory authorities to vote in consensus)

Requirements:

• Public IP with ports 9001, 9030 accessible
• Stable uptime (99%+ recommended)
• 10+ Mbps bandwidth recommended

Exit Relay

What it does:

• Allows Tor traffic to exit to the internet
• Your IP is associated with all exit traffic
• Published in the main Tor directory

Best for:

• Experienced operators who understand legal implications
• Datacenters with abuse handling
• Dedicated servers/IPs

⚠️ CRITICAL REQUIREMENTS:

• Understand legal risks - read EFF Tor Legal FAQ
• Prepare for abuse complaints
• Inform your ISP
• Set up abuse@ email address
• Have legal resources available
• Use dedicated IP/server

obfs4 Bridge

What it does:

• Helps users in censored countries connect to Tor
• NOT published in main directory (distributed via BridgeDB)
• Uses obfs4 to make traffic look random

Best for:

• Operators in non-censored countries
• Lower bandwidth contributions
• Helping circumvent censorship

Requirements:

• Stable IP with ports 9001, 9002 accessible
• Less bandwidth than relays (10+ Mbps sufficient)
• Not blocked by censors in target countries

---

Guard/Middle Relay Mode

Quick Start with Environment Variables

docker run -d \
  --name tor-guard-relay \
  --network host \
  --restart unless-stopped \
  -e TOR_RELAY_MODE=guard \
  -e TOR_NICKNAME=MyGuardRelay \
  -e TOR_CONTACT_INFO="your-email@example.com" \
  -e TOR_BANDWIDTH_RATE="50 MBytes" \
  -e TOR_BANDWIDTH_BURST="100 MBytes" \
  -v tor-guard-data:/var/lib/tor \
  -v tor-guard-logs:/var/log/tor \
  r3bo0tbx1/onion-relay:latest

Docker Compose

version: '3.8'

services:
  tor-guard-relay:
    image: r3bo0tbx1/onion-relay:latest
    container_name: tor-guard-relay
    restart: unless-stopped
    network_mode: host
    environment:
      TOR_RELAY_MODE: guard
      TOR_NICKNAME: MyGuardRelay
      TOR_CONTACT_INFO: "your-email@example.com"
      TOR_BANDWIDTH_RATE: "50 MBytes"
      TOR_BANDWIDTH_BURST: "100 MBytes"
    volumes:
      - tor-guard-data:/var/lib/tor
      - tor-guard-logs:/var/log/tor

volumes:
  tor-guard-data:
  tor-guard-logs:

Save as docker-compose.yml and run:

docker-compose up -d

Verification

# Check status
docker exec tor-guard-relay status

# View logs
docker logs -f tor-guard-relay

# Get fingerprint
docker exec tor-guard-relay fingerprint

---

Exit Relay Mode

⚠️ Before You Start

READ THIS FIRST:

1. EFF Tor Legal FAQ
2. Tor Abuse Response Templates
3. Good/Bad ISPs for Exit Relays

Exit Relay Checklist:

• Read and understand legal implications
• Prepared to handle abuse complaints
• Informed ISP (recommended)
• Set up abuse@ email address
• Using dedicated IP/server
• Have abuse response template ready
• Have legal resources available if needed

Quick Start

docker run -d \
  --name tor-exit-relay \
  --network host \
  --restart unless-stopped \
  -e TOR_RELAY_MODE=exit \
  -e TOR_NICKNAME=MyExitRelay \
  -e TOR_CONTACT_INFO="your-email@example.com <0xPGP_KEY>" \
  -e TOR_BANDWIDTH_RATE="50 MBytes" \
  -e TOR_BANDWIDTH_BURST="100 MBytes" \
  -v tor-exit-data:/var/lib/tor \
  -v tor-exit-logs:/var/log/tor \
  r3bo0tbx1/onion-relay:latest

Exit Policy

By default, uses the Reduced Exit Policy (Tor Project recommended):

• Allows common services (HTTP, HTTPS, SSH, email, etc.)
• Blocks high-risk ports
• Good starting point for exit operators

Custom Exit Policy:

-e TOR_EXIT_POLICY="accept *:80,accept *:443,reject *:*"

More restrictive (HTTPS only):

-e TOR_EXIT_POLICY="accept *:443,reject *:*"

Docker Compose

See templates/docker-compose-exit.yml for complete example.

Handling Abuse Complaints

Standard Response Template:

This is a Tor exit relay (https://www.torproject.org/).
The IP address you reported is not the source of the activity.
Tor is an anonymity network that helps people protect their
privacy and security online.

For more information about Tor and exit relays:
- What is Tor: https://www.torproject.org/about/overview.html
- Tor and abuse: https://blog.torproject.org/blog/tips-running-exit-node

If you have concerns about specific traffic, please contact
the destination website directly. The exit relay operator
does not control the traffic passing through the relay.

Contact: your-email@example.com

---

obfs4 Bridge Mode

Quick Start

docker run -d \
  --name tor-bridge \
  --network host \
  --restart unless-stopped \
  -e TOR_RELAY_MODE=bridge \
  -e TOR_NICKNAME=MyTorBridge \
  -e TOR_CONTACT_INFO="your-email@example.com" \
  -e TOR_ORPORT=9001 \
  -e TOR_OBFS4_PORT=9002 \
  -e TOR_BANDWIDTH_RATE="10 MBytes" \
  -e TOR_BANDWIDTH_BURST="20 MBytes" \
  -v tor-bridge-data:/var/lib/tor \
  -v tor-bridge-logs:/var/log/tor \
  r3bo0tbx1/onion-relay:latest

Docker Compose

See templates/docker-compose-bridge.yml for complete example.

Getting Your Bridge Line

After 24-48 hours, your bridge will be registered and you can get the bridge line:

# Method 1: Check pt_state directory
docker exec tor-bridge cat /var/lib/tor/pt_state/obfs4_bridgeline.txt

# Method 2: Search logs
docker exec tor-bridge grep "bridge line" /var/log/tor/notices.log

# Method 3: Check pt_state directory contents
docker exec tor-bridge ls -la /var/lib/tor/pt_state/

Output will look like:

Bridge obfs4 <IP>:<PORT> <FINGERPRINT> cert=<CERT> iat-mode=0

Sharing Your Bridge

IMPORTANT:

• Only share with people you trust
• Do NOT publish publicly (defeats the purpose)
• Users can also request bridges from BridgeDB

Verification

# Check if obfs4proxy is running
docker exec tor-bridge pgrep -a obfs4proxy

# Check bridge status
docker exec tor-bridge status

---

Configuration Methods

The container supports two configuration methods:

Method 1: Environment Variables (Recommended for Simple Setups)

Pros: ✓ No config file to maintain ✓ Easy to change settings ✓ Good for simple setups ✓ Works well with orchestration tools

Cons: ✗ Less flexible for advanced options ✗ Cannot set all possible Tor directives

Example:

docker run -d \
  -e TOR_RELAY_MODE=guard \
  -e TOR_NICKNAME=MyRelay \
  -e TOR_CONTACT_INFO="email@example.com" \
  ...

Method 2: Config File Mount (Advanced)

Pros: ✓ Full control over Tor configuration ✓ Can use any Tor directive ✓ Better for complex setups

Cons: ✗ Need to maintain config file ✗ Less portable

Example:

docker run -d \
  -v $(pwd)/relay.conf:/etc/tor/torrc:ro \
  ...

Can I Use Both?

Yes! If you mount a config file, it takes precedence over environment variables. The container will detect the mounted file and skip dynamic config generation.

---

Environment Variables Reference

Core Configuration

Variable	Default	Description
TOR_RELAY_MODE	guard	Relay mode: guard, exit, or bridge
TOR_NICKNAME	(required)	Relay nickname (1-19 alphanumeric chars)
TOR_CONTACT_INFO	(required)	Contact email (+ optional PGP key)

Network Ports

Variable	Default	Description
TOR_ORPORT	9001	Tor connection port
TOR_DIRPORT	9030	Directory service port (not used for bridges)
TOR_OBFS4_PORT	9002	obfs4 pluggable transport port (bridges only)

Bandwidth

Variable	Default	Description
TOR_BANDWIDTH_RATE	(none)	Sustained bandwidth (e.g., 50 MBytes)
TOR_BANDWIDTH_BURST	(none)	Burst bandwidth (e.g., 100 MBytes)

Exit Policy (Exit Mode Only)

Variable	Default	Description
TOR_EXIT_POLICY	Reduced Exit Policy	Custom exit policy (comma-separated)

Example: TOR_EXIT_POLICY="accept *:80,accept *:443,reject *:*"

Advanced

Variable	Default	Description
TOR_DATA_DIR	/var/lib/tor	Tor data directory
TOR_LOG_DIR	/var/log/tor	Tor log directory
TOR_CONFIG	/etc/tor/torrc	Tor configuration file path
DEBUG	false	Enable debug output

---

Switching Modes

You can switch between modes by changing TOR_RELAY_MODE and restarting:

From Guard to Exit

docker stop tor-relay
docker rm tor-relay

docker run -d \
  --name tor-relay \
  -e TOR_RELAY_MODE=exit \
  -e TOR_NICKNAME=MyExitRelay \
  ...  # Same volumes

⚠️ WARNING: Switching to exit mode has legal implications. Read the Exit Relay section first.

From Guard to Bridge

docker stop tor-relay
docker rm tor-relay

docker run -d \
  --name tor-relay \
  -e TOR_RELAY_MODE=bridge \
  -e TOR_NICKNAME=MyBridge \
  -e TOR_OBFS4_PORT=9002 \
  ...  # Same volumes

Note: Your relay will get a new identity when switching modes.

---

Troubleshooting

Configuration Not Generating

Symptom: Container starts but uses placeholder config

Solution:

1. Make sure no config file is mounted at /etc/tor/torrc
2. Set required environment variables:
   • TOR_NICKNAME
   • TOR_CONTACT_INFO
3. Check logs: docker logs <container>

Bridge Line Not Appearing

Symptom: Bridge line file doesn't exist after 24+ hours

Solution:

1. Check both ports are accessible: 9001 and 9002
2. Verify obfs4proxy is running: docker exec <container> pgrep obfs4proxy
3. Check logs for obfs4proxy errors: docker logs <container> | grep obfs4
4. Wait 48 hours - bridge distribution takes time

Exit Relay - Too Many Abuse Complaints

Symptom: Receiving excessive abuse complaints

Solutions:

1. Switch to more restrictive exit policy (HTTPS only)
2. Consider running as guard relay instead
3. Check if your ISP supports exit relays: Good/Bad ISPs
4. Use abuse complaint template to respond efficiently

Ports Not Accessible

Symptom: ORPort not reachable in status

Solution:

# Check firewall
sudo ufw status

# Open required ports
sudo ufw allow 9001/tcp
sudo ufw allow 9030/tcp  # Guards/exits only
sudo ufw allow 9002/tcp  # Bridges only

# Test from outside
nc -zv <your-ip> 9001

Low/No Traffic

Symptom: Relay shows very little bandwidth usage

Normal for:

• New relays (2-8 weeks to build reputation)
• Bridges (intentionally low visibility)
• Guards without Guard flag (need 8+ days uptime - at least 5 of 9 directory authorities must agree in consensus)

Check:

1. Verify relay is reachable: docker exec <container> status
2. Check Tor Metrics: https://metrics.torproject.org/rs.html
3. Ensure adequate bandwidth: TOR_BANDWIDTH_RATE

---

Resources

Official Tor Project

• Relay Setup Guide
• Bridge Setup Guide
• Relay Requirements
• Tor Metrics
• BridgeDB

Legal & Compliance

• EFF Tor Legal FAQ
• Abuse Response Templates
• Good/Bad ISPs

Technical Documentation

• obfs4 Specification
• Tor Manual

This Project

• Main README
• Deployment Guide
• Tools Documentation
• Monitoring Guide

---

Made with 💜 for a freer, uncensored internet

Protecting privacy, one relay at a time 🧅✨