feat: doocs
This commit is contained in:
494
Projects/kompose/docs/content/5.stacks/vpn.md
Normal file
494
Projects/kompose/docs/content/5.stacks/vpn.md
Normal file
@@ -0,0 +1,494 @@
|
||||
---
|
||||
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"}
|
||||
Reference in New Issue
Block a user