495 lines
12 KiB
Markdown
495 lines
12 KiB
Markdown
---
|
|
title: VPN - Encrypted Tunnel to Freedom
|
|
description: "The internet, but make it private!"
|
|
navigation:
|
|
icon: i-lucide-plug
|
|
---
|
|
|
|
> *"The internet, but make it private!"* - WireGuard
|
|
|
|
## What's This All About?
|
|
|
|
WG-Easy is your self-hosted VPN server powered by WireGuard! It's like having your own private tunnel through the internet - encrypt all your traffic, bypass geo-restrictions, access your home network from anywhere, and surf safely on sketchy public WiFi. Plus, it has a beautiful web UI for managing clients! 🚇
|
|
|
|
## The Privacy Protector
|
|
|
|
### :icon{name="lucide:shield"} WG-Easy
|
|
|
|
**Container**: `vpn_app`
|
|
**Image**: `ghcr.io/wg-easy/wg-easy:15`
|
|
**Ports**: 51820 (VPN), 51821 (Web UI)
|
|
**Home**: https://vpn.pivoine.art
|
|
|
|
WG-Easy makes WireGuard actually easy:
|
|
- :icon{name="lucide:palette"} **Beautiful Web UI**: Manage VPN from browser
|
|
- 📱 **QR Codes**: Instant mobile setup
|
|
- :icon{name="lucide:users"} **Multi-Client**: Unlimited devices
|
|
- :icon{name="lucide:zap"} **WireGuard**: Modern, fast, secure protocol
|
|
- :icon{name="lucide:bar-chart"} **Traffic Stats**: See bandwidth usage
|
|
- :icon{name="lucide:lock"} **Encrypted**: Industry-standard crypto
|
|
- 🌍 **Route All Traffic**: Or split-tunnel
|
|
- :icon{name="lucide:rocket"} **Performance**: Faster than OpenVPN
|
|
|
|
## WireGuard: The Modern VPN Protocol
|
|
|
|
### Why WireGuard is Awesome
|
|
- :icon{name="lucide:zap"} **Fast**: 4000+ lines of code vs OpenVPN's 600,000+
|
|
- :icon{name="lucide:lock"} **Secure**: State-of-the-art cryptography
|
|
- 📱 **Battery Friendly**: Less power consumption
|
|
- :icon{name="lucide:refresh-cw"} **Roaming**: Seamless connection switching
|
|
- 🐧 **Linux Kernel**: Built into Linux 5.6+
|
|
- :icon{name="lucide:target"} **Simple**: Easier to audit and configure
|
|
|
|
## Configuration Breakdown
|
|
|
|
### Network Configuration
|
|
|
|
The stack creates TWO networks:
|
|
|
|
**wg Network** (Internal WireGuard):
|
|
```yaml
|
|
subnet: 10.42.42.0/24 # IPv4
|
|
subnet: fdcc:ad94:bacf:61a3::/64 # IPv6
|
|
```
|
|
Your VPN clients get IPs from this range.
|
|
|
|
**kompose Network** (External):
|
|
```yaml
|
|
external: true
|
|
```
|
|
Connects to other services via Traefik.
|
|
|
|
### Environment Variables
|
|
|
|
**WireGuard Settings**:
|
|
```bash
|
|
WG_HOST=vpn.pivoine.art # Your public domain/IP
|
|
WG_PORT=51820 # WireGuard port (UDP)
|
|
WG_DEFAULT_ADDRESS=10.42.0.x # Client IP range
|
|
WG_DEFAULT_DNS=1.1.1.1 # DNS for clients
|
|
WG_ALLOWED_IPS=0.0.0.0/0 # Route all traffic through VPN
|
|
```
|
|
|
|
**Web UI Settings**:
|
|
```bash
|
|
PORT=51821 # Web interface port
|
|
UI_TRAFFIC_STATS=true # Show bandwidth graphs
|
|
UI_CHART_TYPE=0 # Chart style
|
|
```
|
|
|
|
### Security & Capabilities
|
|
|
|
Required Linux capabilities:
|
|
```yaml
|
|
cap_add:
|
|
- NET_ADMIN # Network configuration
|
|
- SYS_MODULE # Load kernel modules
|
|
```
|
|
|
|
System controls:
|
|
```yaml
|
|
sysctls:
|
|
- net.ipv4.ip_forward=1 # Enable IP forwarding
|
|
- net.ipv4.conf.all.src_valid_mark=1 # Packet routing
|
|
```
|
|
|
|
## First Time Setup :icon{name="lucide:rocket"}
|
|
|
|
### 1. Ensure Ports are Open
|
|
|
|
**Firewall**:
|
|
```bash
|
|
# Allow WireGuard port
|
|
sudo ufw allow 51820/udp
|
|
|
|
# Allow Web UI (temporary for setup)
|
|
sudo ufw allow 51821/tcp
|
|
```
|
|
|
|
**Router**:
|
|
- Forward UDP port 51820 to your server
|
|
- Check your router's port forwarding settings
|
|
|
|
### 2. Set Your Public Address
|
|
|
|
In `.env`:
|
|
```bash
|
|
# Use your domain
|
|
WG_HOST=vpn.yourdomain.com
|
|
|
|
# Or your public IP
|
|
WG_HOST=123.45.67.89
|
|
```
|
|
|
|
### 3. Start the Stack
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### 4. Access Web UI
|
|
```
|
|
URL: https://vpn.pivoine.art
|
|
Password: (set via PASSWORD_HASH in .env)
|
|
```
|
|
|
|
### 5. Generate Password Hash
|
|
|
|
If you haven't set password yet:
|
|
```bash
|
|
# Generate bcrypt hash
|
|
echo -n 'your-password' | npx bcrypt-cli
|
|
|
|
# Or use Docker
|
|
docker run --rm -it node:alpine sh -c "npm install -g bcrypt-cli && echo -n 'your-password' | bcrypt"
|
|
|
|
# Copy hash to .env
|
|
PASSWORD_HASH=$2a$10$...your_hash...
|
|
```
|
|
|
|
Restart container:
|
|
```bash
|
|
docker compose restart
|
|
```
|
|
|
|
## Creating VPN Clients 📱
|
|
|
|
### Add a Client
|
|
|
|
1. **Login to Web UI**: https://vpn.pivoine.art
|
|
2. **Click "New Client"**
|
|
3. **Give it a name**: "My iPhone", "Work Laptop", etc.
|
|
4. **Click "Create"**
|
|
|
|
### Mobile Setup (QR Code)
|
|
|
|
**For iPhone/Android**:
|
|
1. Install WireGuard app:
|
|
- [iOS](https://apps.apple.com/app/wireguard/id1441195209)
|
|
- [Android](https://play.google.com/store/apps/details?id=com.wireguard.android)
|
|
|
|
2. Open app → "Add tunnel" → "Scan QR code"
|
|
3. Scan the QR code from web UI
|
|
4. Give tunnel a name
|
|
5. Toggle on!
|
|
|
|
### Desktop Setup (Config File)
|
|
|
|
**For Windows/Mac/Linux**:
|
|
1. Download WireGuard:
|
|
- [Windows](https://download.wireguard.com/windows-client/)
|
|
- [macOS](https://apps.apple.com/app/wireguard/id1451685025)
|
|
- [Linux](https://www.wireguard.com/install/)
|
|
|
|
2. In web UI, click "Download" next to client
|
|
3. Import config file into WireGuard app
|
|
4. Activate tunnel!
|
|
|
|
### Manual Configuration
|
|
|
|
Download the `.conf` file and inspect it:
|
|
```ini
|
|
[Interface]
|
|
PrivateKey = your_private_key
|
|
Address = 10.42.0.2/32
|
|
DNS = 1.1.1.1
|
|
|
|
[Peer]
|
|
PublicKey = server_public_key
|
|
PresharedKey = shared_key
|
|
Endpoint = vpn.pivoine.art:51820
|
|
AllowedIPs = 0.0.0.0/0, ::/0
|
|
PersistentKeepalive = 25
|
|
```
|
|
|
|
## Using Your VPN :icon{name="lucide:globe"}
|
|
|
|
### Full Tunnel (All Traffic)
|
|
|
|
**Default behavior** - all internet traffic goes through VPN:
|
|
- ✅ Complete privacy
|
|
- ✅ Bypass geo-blocks
|
|
- ✅ Secure public WiFi
|
|
- :icon{name="lucide:alert-triangle"} Slightly slower (routing through your server)
|
|
|
|
### Split Tunnel (Selective Routing)
|
|
|
|
**Only route specific traffic** through VPN.
|
|
|
|
Edit client config to only route home network:
|
|
```ini
|
|
AllowedIPs = 10.0.0.0/24 # Only home network
|
|
# Instead of: 0.0.0.0/0
|
|
```
|
|
|
|
**Benefits**:
|
|
- :icon{name="lucide:home"} Access home services
|
|
- :icon{name="lucide:globe"} Normal internet speed
|
|
- :icon{name="lucide:bar-chart"} Less VPN bandwidth
|
|
|
|
## Traffic Statistics :icon{name="lucide:bar-chart"}
|
|
|
|
Web UI shows for each client:
|
|
- 📥 **Download**: Data received
|
|
- 📤 **Upload**: Data sent
|
|
- 🕐 **Last Seen**: When last connected
|
|
- :icon{name="lucide:trending-up"} **Charts**: Bandwidth over time
|
|
|
|
## Common Use Cases
|
|
|
|
### 1. Secure Public WiFi :icon{name="lucide:coffee"}
|
|
```
|
|
Coffee Shop WiFi → WireGuard → Your Server → Internet
|
|
```
|
|
Encrypt traffic on untrusted networks.
|
|
|
|
### 2. Access Home Network :icon{name="lucide:home"}
|
|
```
|
|
You (anywhere) → VPN → Home Network → NAS, Printer, etc.
|
|
```
|
|
Access devices as if you're home.
|
|
|
|
### 3. Bypass Geo-Restrictions 🌍
|
|
```
|
|
Your Location → VPN (Server Country) → Streaming Service
|
|
```
|
|
Appear to be in server's location.
|
|
|
|
### 4. Privacy from ISP 🕵️
|
|
```
|
|
Your Device → Encrypted Tunnel → Your Server → Internet
|
|
```
|
|
ISP only sees encrypted traffic to your server.
|
|
|
|
### 5. Multiple Locations 🗺️
|
|
Deploy VPN servers in different countries:
|
|
- USA server for US content
|
|
- EU server for European services
|
|
- Home server for local access
|
|
|
|
## Security Features :icon{name="lucide:lock"}
|
|
|
|
### Encryption
|
|
- **Protocol**: Noise Protocol Framework
|
|
- **Key Exchange**: Curve25519
|
|
- **Cipher**: ChaCha20-Poly1305
|
|
- **Hash**: BLAKE2s
|
|
|
|
**Translation**: Military-grade encryption! :icon{name="lucide:dumbbell"}
|
|
|
|
### Authentication
|
|
- **Public/Private Keys**: Per-client keypairs
|
|
- **Preshared Keys**: Extra security layer
|
|
- **Endpoint Verification**: Prevents spoofing
|
|
|
|
### Privacy
|
|
- **No Logs**: WireGuard doesn't log by default
|
|
- **Perfect Forward Secrecy**: Past sessions stay secure
|
|
- **IP Masquerading**: Hides your real IP
|
|
|
|
## DNS Configuration :icon{name="lucide:globe"}
|
|
|
|
### Default DNS (Cloudflare)
|
|
```bash
|
|
WG_DEFAULT_DNS=1.1.1.1
|
|
```
|
|
|
|
### Other Options
|
|
|
|
**Google**:
|
|
```bash
|
|
WG_DEFAULT_DNS=8.8.8.8
|
|
```
|
|
|
|
**Quad9** (Security):
|
|
```bash
|
|
WG_DEFAULT_DNS=9.9.9.9
|
|
```
|
|
|
|
**AdGuard** (Ad-blocking):
|
|
```bash
|
|
WG_DEFAULT_DNS=94.140.14.14
|
|
```
|
|
|
|
**Custom** (Your Pi-hole):
|
|
```bash
|
|
WG_DEFAULT_DNS=192.168.1.2
|
|
```
|
|
|
|
## Performance Optimization :icon{name="lucide:zap"}
|
|
|
|
### Enable BBR (Better Congestion Control)
|
|
```bash
|
|
# On host
|
|
echo "net.core.default_qdisc=fq" >> /etc/sysctl.conf
|
|
echo "net.ipv4.tcp_congestion_control=bbr" >> /etc/sysctl.conf
|
|
sysctl -p
|
|
```
|
|
|
|
### Increase MTU
|
|
```ini
|
|
# In client config
|
|
[Interface]
|
|
MTU = 1420 # Default, try 1500 if stable
|
|
```
|
|
|
|
### Persistent Keepalive
|
|
```ini
|
|
# Keep connection alive through NAT
|
|
PersistentKeepalive = 25
|
|
```
|
|
|
|
## Troubleshooting :icon{name="lucide:wrench"}
|
|
|
|
**Q: Can't connect to VPN?**
|
|
```bash
|
|
# Check server is running
|
|
docker logs vpn_app
|
|
|
|
# Verify port is open
|
|
nc -zvu vpn.pivoine.art 51820
|
|
|
|
# Check firewall
|
|
sudo ufw status
|
|
```
|
|
|
|
**Q: Connected but no internet?**
|
|
```bash
|
|
# Verify IP forwarding
|
|
sysctl net.ipv4.ip_forward
|
|
# Should return: 1
|
|
|
|
# Check NAT rules
|
|
sudo iptables -t nat -L
|
|
```
|
|
|
|
**Q: Slow speeds?**
|
|
- Check server bandwidth
|
|
- Try different MTU values
|
|
- Enable BBR congestion control
|
|
- Use split-tunnel for non-sensitive traffic
|
|
|
|
**Q: Client won't auto-reconnect?**
|
|
- Add `PersistentKeepalive = 25` to config
|
|
- Check client has network connectivity
|
|
|
|
**Q: DNS not working?**
|
|
```bash
|
|
# Test DNS from client
|
|
nslookup google.com
|
|
|
|
# Change DNS in config
|
|
DNS = 8.8.8.8
|
|
```
|
|
|
|
## Mobile Tips 📱
|
|
|
|
### iOS
|
|
- **On-Demand**: Auto-connect on untrusted WiFi
|
|
- **Shortcuts**: Create Siri shortcuts
|
|
- **Widget**: Quick toggle from home screen
|
|
|
|
### Android
|
|
- **Always-On**: VPN reconnects automatically
|
|
- **Kill Switch**: Block internet if VPN drops
|
|
- **Split Tunneling**: Exclude specific apps
|
|
|
|
## Advanced Configuration
|
|
|
|
### IPv6 Support
|
|
Already configured!
|
|
```yaml
|
|
enable_ipv6: true
|
|
subnet: fdcc:ad94:bacf:61a3::/64
|
|
```
|
|
|
|
### Custom Routing
|
|
|
|
**Route only specific subnets**:
|
|
```ini
|
|
AllowedIPs = 192.168.1.0/24, 10.0.0.0/24
|
|
```
|
|
|
|
**Block specific IPs**:
|
|
```bash
|
|
# On server
|
|
iptables -A FORWARD -d 192.168.1.100 -j DROP
|
|
```
|
|
|
|
### Port Forwarding
|
|
|
|
Forward ports through VPN:
|
|
```bash
|
|
# Forward port 8080 to client
|
|
iptables -t nat -A PREROUTING -p tcp --dport 8080 -j DNAT --to 10.42.0.2:8080
|
|
```
|
|
|
|
## Monitoring & Logs
|
|
|
|
### Check Connection Status
|
|
```bash
|
|
# Via web UI
|
|
https://vpn.pivoine.art
|
|
|
|
# Or check container
|
|
docker exec vpn_app wg show
|
|
```
|
|
|
|
### View Logs
|
|
```bash
|
|
docker logs vpn_app -f
|
|
```
|
|
|
|
### Bandwidth Stats
|
|
Web UI shows real-time graphs for each client!
|
|
|
|
## Backup & Restore :icon{name="lucide:refresh-cw"}
|
|
|
|
### Backup Configuration
|
|
```bash
|
|
# Backup WireGuard configs
|
|
docker exec vpn_app tar -czf /tmp/wg-backup.tar.gz /etc/wireguard
|
|
docker cp vpn_app:/tmp/wg-backup.tar.gz ./backups/
|
|
```
|
|
|
|
### Restore
|
|
```bash
|
|
# Copy backup to container
|
|
docker cp ./backups/wg-backup.tar.gz vpn_app:/tmp/
|
|
|
|
# Extract
|
|
docker exec vpn_app tar -xzf /tmp/wg-backup.tar.gz -C /
|
|
|
|
# Restart
|
|
docker compose restart
|
|
```
|
|
|
|
## Security Best Practices :icon{name="lucide:shield"}
|
|
|
|
1. **Strong Password**: Use bcrypt hash for web UI
|
|
2. **Regular Updates**: Keep WG-Easy updated
|
|
3. **Firewall**: Only expose necessary ports
|
|
4. **Client Management**: Remove inactive clients
|
|
5. **Monitoring**: Watch for unusual traffic
|
|
6. **Backups**: Regular config backups
|
|
7. **Access Control**: Limit who can create clients
|
|
|
|
## Why Self-Host a VPN?
|
|
|
|
- :icon{name="lucide:lock"} **Full Control**: Your server, your rules
|
|
- :icon{name="lucide:dollar-sign"} **Cost Effective**: No monthly fees
|
|
- :icon{name="lucide:rocket"} **Performance**: Direct to your server
|
|
- 🕵️ **Privacy**: No third-party logging
|
|
- 🌍 **Flexibility**: Use any server location
|
|
- :icon{name="lucide:bar-chart"} **Transparency**: You know what's happening
|
|
- :icon{name="lucide:hammer"} **Customization**: Configure exactly as needed
|
|
|
|
## Resources
|
|
|
|
- [WireGuard Documentation](https://www.wireguard.com/)
|
|
- [WG-Easy GitHub](https://github.com/wg-easy/wg-easy)
|
|
- [WireGuard Clients](https://www.wireguard.com/install/)
|
|
|
|
---
|
|
|
|
*"Privacy is not about having something to hide. It's about protecting what you value."* - VPN Philosophy :icon{name="lucide:lock"}:icon{name="lucide:sparkles"}
|