Wirehole - Privacy-Focused VPN with DNS Filtering

A complete Docker-based setup combining Wireguard VPN, Pihole ad-blocking, Unbound recursive DNS, and optional Tor routing for maximum privacy and security.

🔧 Components

• Wireguard VPN Server - Secure VPN tunnel
• Pihole - Network-wide ad blocking and DNS sinkhole
• Unbound - Recursive DNS resolver (no third-party logging)
• Tor Proxy - Optional rotating SOCKS5 proxy for anonymity

🚀 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Port 51820/UDP open on your firewall
• Static IP or dynamic DNS for external access

Setup

1. Clone and configure:

   git clone <your-repo>
   cd wirehole
   cp .env.example .env
   # Edit .env with your settings

2. Start services:

   # Start without Tor proxy
   docker-compose up -d wireguard pihole unbound
   
   # Or start everything including Tor
   docker-compose up -d

3. Get client configurations:

   docker logs wireguard
   # QR codes and config files in ./wireguard/peer*/

📱 Client Setup

Import Wireguard Config

• Mobile: Scan QR code from logs
• Desktop: Import .conf file from ./wireguard/peer*/

DNS Configuration

DNS is automatically set to your Pihole (10.72.1.2) via Wireguard.

🌐 Access Services

Once connected to Wireguard VPN:

• Pihole Admin: http://10.72.1.2/admin
• Tor SOCKS5 Proxy: 10.72.1.4:9050 (if enabled)

🔒 Security Features

Network Isolation

• All services bound to Wireguard network only
• No external access except SSH and Wireguard ports
• Pihole web interface only accessible via VPN

Privacy Configuration

• Unbound: Full recursive DNS (no third-party logging)
• Pihole: Query logging disabled by default
• Tor: Multiple rotating circuits for anonymity

IP Ranges

10.72.1.1 - Wireguard Server
10.72.1.2 - Pihole DNS
10.72.1.3 - Unbound Recursive DNS  
10.72.1.4 - Tor Proxy (optional)
10.72.1.5+ - Wireguard Clients

🌍 Using Tor Proxy

When connected to Wireguard, configure applications to use:

• SOCKS5 Proxy: 10.72.1.4:9050
• Protocol: SOCKS5 (no authentication)

Browser Setup (Firefox)

1. Install FoxyProxy extension
2. Add new proxy:
   • Type: SOCKS5
   • IP: 10.72.1.4
   • Port: 9050

🛠️ Configuration

Environment Variables (.env)

TZ=America/Chicago
PIHOLE_PASSWORD=your_secure_password
SERVERURL=your.domain.com
PEERS=5

Pihole Custom Configuration

Modern Pihole versions use pihole.toml instead of lighttpd:

[webserver]
port = "10.72.1.2:80"  # VPN-only access

Unbound Configuration

Full recursive DNS with privacy focus:

• Only listens on Wireguard network
• DNSSEC validation enabled
• Query minimization for privacy

🔧 Management

View Logs

docker logs pihole
docker logs unbound  
docker logs wireguard
docker logs tor-proxy

Restart Services

docker-compose restart pihole
docker-compose restart wireguard

Add More Clients

# Edit PEERS in .env file, then:
docker-compose down wireguard
docker-compose up -d wireguard

Update Blocklists

docker exec pihole pihole -g

🚨 Important Notes

Security Considerations

• Change default Pihole password in .env
• Use strong passwords for all services
• Keep Docker images updated regularly
• Monitor logs for suspicious activity

Tor Usage Warning

• Tor traffic may be blocked by some services
• Use responsibly and legally
• Consider detection by security tools
• Rotating IP addresses may trigger rate limits

Backup Important Data

# Backup Wireguard configs
tar -czf wireguard-backup.tar.gz ./wireguard/

# Backup Pihole settings  
tar -czf pihole-backup.tar.gz ./pihole/

🐛 Troubleshooting

Wireguard Issues

# Check if UDP port is open
nc -u your-server-ip 51820

# Verify container networking
docker exec wireguard wg show

DNS Issues

# Test Unbound
dig @10.72.1.3 -p 5335 google.com

# Test Pihole
dig @10.72.1.2 google.com

Tor Issues

# Check Tor instances
docker exec tor-proxy ps aux | grep tor

# Test SOCKS connection
curl --socks5 10.72.1.4:9050 https://check.torproject.org/

📊 Performance

• RAM Usage: ~512MB total for all services
• CPU: Minimal load on modern hardware
• Storage: ~100MB for Docker images + configs
• Bandwidth: Depends on usage and Tor routing

🔄 Updates

# Update all images
docker-compose pull
docker-compose up -d

# Check for new versions
docker images | grep -E 'pihole|wireguard|unbound'

---

⚠️ Disclaimer: This setup is for educational and legitimate privacy purposes only. Always comply with local laws and obtain proper authorization before use.