vpn/PROJECT_SUMMARY.md

Project Summary

Overview

This project implements a split-tunnel VPN network for bypassing internet restrictions in Russia while maintaining optimal performance for domestic traffic.

Architecture

3-node setup:

• Client devices (users in Russia)
• RU VDS (176.124.216.197) - Gateway with selective routing
• DE VDS (194.31.173.178) - Exit node in Germany

Key feature: IP-based selective routing

• Russian IP ranges (from RIPE database) → Direct routing (fast, no proxy)
• All other IPs → Routed through Germany (bypass blocks)

Technology Stack

Component	Purpose
WireGuard	VPN tunnels (lightweight, fast)
dnsmasq	DNS server for VPN clients
nftables	Firewall, NAT, and packet marking (pure nftables, no iptables)
iproute2	Policy-based routing

What's Included

Documentation (5 files)

1. README.md - Architecture overview and reference
2. QUICKSTART.md - 30-minute setup guide
3. IMPLEMENTATION.md - Detailed step-by-step implementation
4. DEPLOYMENT.md - Production deployment guide
5. TESTING.md - Comprehensive testing checklist

Configuration Files (11 files)

DE VDS configs:

• wg0.conf - WireGuard interface config
• nftables.conf - Firewall rules (NAT)
• 99-vpn.conf - Kernel parameters (IP forwarding)

RU VDS configs:

• wg0.conf - User-facing VPN interface
• wg1.conf - DE tunnel interface
• postup.sh - Routing setup script
• postdown.sh - Routing cleanup script
• nftables.conf - Firewall and packet marking rules
• vpn-routing.conf - dnsmasq config
• update-direct-routes.sh - Russian IP ranges loader
• rt_tables - Custom routing table definitions
• 99-vpn.conf - Kernel parameters

Client template:

• example-client.conf - Template for client configs

Management Scripts (7 files)

Setup:

• setup-de-vds.sh - Automated DE VDS setup
• setup-ru-vds.sh - Automated RU VDS setup

Client management:

• add-client.sh - Add new VPN client (with QR code)
• remove-client.sh - Permanently remove client
• disable-client.sh - Temporarily disable client
• enable-client.sh - Re-enable disabled client
• list-clients.sh - List all clients with status

Key Features

Automated Setup

• One-command server deployment
• Automatic key generation
• Automatic package installation
• Automatic service configuration

Easy Client Management

• Simple CLI commands
• Automatic IP assignment
• QR code generation for mobile
• Enable/disable without key regeneration

Smart Routing

• IP-based routing using RIPE database
• Automatic weekly updates of Russian IP ranges
• Pure nftables implementation (no iptables/ipset mixing)
• Optimal performance for local traffic

Security

• WireGuard modern cryptography
• Restricted firewall rules
• Key-based authentication
• Isolated VPN network

Scalability

• Support for 253 concurrent clients
• Low resource usage
• Efficient packet routing
• No bottlenecks

Network Topology

                                Internet
                                    ▲
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
                    │           Direct (fast)       │
                    │           .ru/.рф domains     │
                    │                               │
    ┌──────────┐    │    ┌──────────────┐          │    ┌──────────┐
    │  Client  │◄───┼───►│   RU VDS     │◄─────────┼───►│  DE VDS  │
    │  Device  │    │    │   Gateway    │          │    │Exit Node │
    └──────────┘    │    └──────────────┘          │    └──────────┘
                    │            │                  │
                    │            │                  │
                    │            ▼                  │
                    │    Routing Decision           │
                    │    (nftables + RIPE data)     │
                    │                               │
                    │        WireGuard tunnel       │
                    │        (all other domains)    │
                    └───────────────────────────────┘

IP Addressing

• User VPN: 10.10.0.0/24 (clients ↔ RU VDS)

  • 10.10.0.1 - RU VDS gateway
  • 10.10.0.2-254 - Client IPs

• Server VPN: 10.20.0.0/30 (RU ↔ DE tunnel)

  • 10.20.0.1 - RU VDS
  • 10.20.0.2 - DE VDS

Deployment Workflow

1. Prepare (5 min)

   • Verify server access
   • Copy setup scripts

2. Deploy DE VDS (5 min)

   • Run setup script
   • Save public key

3. Deploy RU VDS (5 min)

   • Run setup script
   • Save public keys

4. Exchange Keys (3 min)

   • Update DE config with RU key
   • Update RU config with DE key

5. Start Services (2 min)

   • Start DE services
   • Start RU services

6. Verify (5 min)

   • Test tunnel connectivity
   • Check routing tables

7. Add Clients (5 min each)

   • Run add-client script
   • Transfer config to device

Total time: ~30-40 minutes

Testing Coverage

Comprehensive testing checklist covers:

• Pre-deployment verification
• Post-setup validation
• Tunnel connectivity
• DNS resolution
• Routing logic
• Client management
• Performance benchmarks
• Security verification
• Failure recovery

Maintenance

Regular Tasks

• Monitor logs for errors
• Check client list for inactive users
• Review bandwidth usage
• Update system packages

Backup Strategy

• Backup /etc/wireguard/ directory
• Store keys securely offline
• Document client assignments

Monitoring

• WireGuard handshake status
• DNS query logs (optional)
• System resource usage
• Network traffic patterns

Troubleshooting Quick Reference

Issue	Check	Fix
Tunnel down	wg show	Restart wg-quick services
DNS not working	systemctl status dnsmasq	Restart dnsmasq
Routing wrong	nft list set ip vpn-routing direct	Run update-direct-routes.sh
Client can't connect	wg show wg0 peers	Verify peer added
Slow performance	ping tests	Check MTU settings

Security Considerations

• Keys stored with 600 permissions
• Firewall restricts access by IP
• DNS only accessible from VPN clients
• Separate interfaces for users/tunnel
• No logging of DNS queries (configurable)

Future Enhancements (Optional)

Potential additions:

• Web UI for client management
• Prometheus metrics export
• Automated key rotation
• Fail-over to secondary DE server
• IPv6 support
• Traffic statistics dashboard

Repository Structure

vpn.git/
├── README.md              # Architecture and reference
├── QUICKSTART.md         # Fast setup guide
├── IMPLEMENTATION.md     # Detailed implementation
├── DEPLOYMENT.md         # Production deployment
├── TESTING.md           # Testing checklist
├── PROJECT_SUMMARY.md   # This file
├── .gitignore           # Git ignore rules
├── configs/             # All configuration files
│   ├── de-vds/         # DE VDS configs
│   ├── ru-vds/         # RU VDS configs
│   └── client-templates/ # Client config templates
└── scripts/            # Management scripts
    ├── setup-*.sh      # Server setup
    └── *-client.sh     # Client management

Success Metrics

After deployment, you should have:

• ✓ Stable VPN tunnel between RU and DE
• ✓ Working client connections
• ✓ Correct routing for .ru vs other domains
• ✓ Simple client management via CLI
• ✓ No errors in service logs
• ✓ Acceptable performance (latency, bandwidth)

Support and Documentation

All information needed is in this repository:

• Architecture → README.md
• Quick setup → QUICKSTART.md
• Detailed steps → IMPLEMENTATION.md
• Deployment → DEPLOYMENT.md
• Testing → TESTING.md

License

This is a personal project. Use at your own discretion.

Credits

Built with:

• WireGuard - Jason A. Donenfeld
• dnsmasq - Simon Kelley
• nftables - Netfilter Project