A production-ready Tor relay implementation in C++20 supporting runtime mode switching between Middle, Exit, and Bridge relay modes.
- Multiple Relay Modes: Middle (default), Exit, and Bridge
- Modern C++20: Uses
std::expected, concepts, ranges - Async I/O: Built on Boost.Asio for high performance
- Strong Cryptography: Ed25519, Curve25519, AES-128-CTR via OpenSSL 3.x
- ntor Handshake: Secure circuit key exchange
- Exit Policies: Flexible rule-based traffic filtering
- Docker Support: Easy deployment with Docker Compose
- Comprehensive Tests: Unit and integration tests with Catch2
# Install dependencies (Ubuntu/Debian)
sudo apt install build-essential cmake libssl-dev libboost-all-dev
# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --parallel
# Run as middle relay
./tor_relay --mode middle --port 9001# Build and run
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down# Deploy to your VPS
./deploy/deploy.sh [email protected] --mode middle
# Manage remotely
./deploy/remote-manage.sh [email protected] logs
./deploy/remote-manage.sh [email protected] restart| Mode | Description | Risk Level | Use Case |
|---|---|---|---|
| Middle | Forward relay cells only | Low | Default, safest option |
| Exit | Connect to external internet | High | Requires careful policy |
| Bridge | Unlisted entry point | Medium | Help censored users |
Copy and edit the example configuration:
cp config/relay.toml.example config/relay.tomlKey settings:
[relay]
nickname = "MyRelay"
mode = "middle" # middle, exit, or bridge
or_port = 9001
[relay.bandwidth]
rate = 10485760 # 10 MB/s
[exit]
exit_policy = """
accept *:80
accept *:443
reject *:*
"""See docs/configuration.md for full options.
- Overview - Architecture and concepts
- Installation - Build instructions
- Configuration - All config options
- Deployment - Docker and VPS deployment
- Architecture - Technical deep-dive
- Security - Security considerations
- Testing - Running tests
- API Reference - Code documentation
- Troubleshooting - Common issues
tor_relay/
├── include/tor/ # Header files
│ ├── core/ # Cell, circuit, channel, relay
│ ├── crypto/ # Keys, ntor, AES, hashing
│ ├── modes/ # Middle, exit, bridge behaviors
│ ├── net/ # Network connections
│ ├── policy/ # Exit policy, bandwidth
│ ├── protocol/ # Link and relay protocols
│ ├── directory/ # Descriptors, consensus
│ └── util/ # Config, logging, errors
├── src/ # Implementation files
├── tests/ # Unit and integration tests
├── config/ # Example configurations
├── deploy/ # Deployment scripts
├── docs/ # Documentation
├── Dockerfile # Docker build
└── docker-compose.yml # Docker Compose config
- Compiler: GCC 11+, Clang 14+, or MSVC 2022+
- CMake: 3.21+
- OpenSSL: 3.0+
- Boost: 1.82+
- Docker: 20.10+ (optional)
# Build with tests
cmake .. -DBUILD_TESTING=ON
cmake --build .
# Run all tests
ctest --output-on-failure
# Run specific category
ctest -L unit
ctest -L integration
ctest -L crypto- Fork the repository
- Create a feature branch
- Write tests for new functionality
- Submit a pull request
For security issues, please email [email protected] rather than opening a public issue.
MIT License - See LICENSE for details.