New branch
This commit is contained in:
commit
58d70409b5
31 changed files with 9093 additions and 0 deletions
320
docs/API.md
Normal file
320
docs/API.md
Normal file
|
|
@ -0,0 +1,320 @@
|
|||
# API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The VPN Gateway provides a RESTful API for managing VPN connections and configuration.
|
||||
|
||||
Base URL: `http://<gateway-ip>:5000`
|
||||
|
||||
## Authentication
|
||||
|
||||
Currently, the API does not require authentication for local network access. For production use, consider implementing API keys or JWT tokens.
|
||||
|
||||
## Endpoints
|
||||
|
||||
### System Status
|
||||
|
||||
#### GET /api/status
|
||||
Get current VPN and system status.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"connected": true,
|
||||
"provider": "mullvad",
|
||||
"server": "se-sto-wg-001",
|
||||
"ip": "185.65.134.123",
|
||||
"location": "Stockholm, Sweden",
|
||||
"uptime": "2h 34m",
|
||||
"killswitch_active": true
|
||||
}
|
||||
```
|
||||
|
||||
### Provider Management
|
||||
|
||||
#### GET /api/providers
|
||||
List available providers.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"providers": ["mullvad", "custom", "imported"],
|
||||
"current": "mullvad"
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /api/provider/{provider}
|
||||
Switch to a different provider.
|
||||
|
||||
**Parameters:**
|
||||
- `provider`: Provider name (mullvad|custom|imported)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"provider": "custom"
|
||||
}
|
||||
```
|
||||
|
||||
### Server Management
|
||||
|
||||
#### GET /api/servers
|
||||
Get available servers for current provider.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"Sweden": {
|
||||
"Stockholm": [
|
||||
{
|
||||
"hostname": "se-sto-wg-001",
|
||||
"ipv4": "185.65.134.123",
|
||||
"type": "WireGuard",
|
||||
"provider": "Mullvad"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"provider": "mullvad"
|
||||
}
|
||||
```
|
||||
|
||||
### Connection Management
|
||||
|
||||
#### POST /api/connect
|
||||
Connect to VPN server.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"server": "se-sto-wg-001"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /api/disconnect
|
||||
Disconnect from VPN.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Disconnected - No internet (killswitch active)"
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Server Management
|
||||
|
||||
#### POST /api/custom/add
|
||||
Add a custom WireGuard server.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "my-vps",
|
||||
"endpoint": "1.2.3.4:51820",
|
||||
"public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
|
||||
"private_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy=",
|
||||
"address": "10.0.0.2/32",
|
||||
"dns": "1.1.1.1,1.0.0.1",
|
||||
"allowed_ips": "0.0.0.0/0,::/0",
|
||||
"location": "Germany"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
#### DELETE /api/custom/remove/{name}
|
||||
Remove a custom server.
|
||||
|
||||
**Parameters:**
|
||||
- `name`: Server name
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### Import Configuration
|
||||
|
||||
#### POST /api/import
|
||||
Import a WireGuard configuration.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "imported-config",
|
||||
"config": "[Interface]\nPrivateKey = xxx\n..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### Utility
|
||||
|
||||
#### GET /api/keypair
|
||||
Generate a new WireGuard keypair.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"private_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
|
||||
"public_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy="
|
||||
}
|
||||
```
|
||||
|
||||
#### GET /health
|
||||
Health check endpoint.
|
||||
|
||||
**Response:**
|
||||
```
|
||||
healthy
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints may return error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Error message here"
|
||||
}
|
||||
```
|
||||
|
||||
Common HTTP status codes:
|
||||
- `200`: Success
|
||||
- `400`: Bad request
|
||||
- `404`: Not found
|
||||
- `500`: Internal server error
|
||||
|
||||
## WebSocket Events (Future)
|
||||
|
||||
Planned WebSocket support for real-time updates:
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://gateway-ip:5000/ws');
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Event:', data.type, data.payload);
|
||||
};
|
||||
```
|
||||
|
||||
Events:
|
||||
- `status_change`: VPN connection status changed
|
||||
- `server_update`: Server list updated
|
||||
- `security_alert`: Security issue detected
|
||||
|
||||
## Example Usage
|
||||
|
||||
### cURL
|
||||
|
||||
```bash
|
||||
# Get status
|
||||
curl http://gateway-ip:5000/api/status
|
||||
|
||||
# Connect to server
|
||||
curl -X POST http://gateway-ip:5000/api/connect \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"server":"se-sto-wg-001"}'
|
||||
|
||||
# Add custom server
|
||||
curl -X POST http://gateway-ip:5000/api/custom/add \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "my-server",
|
||||
"endpoint": "1.2.3.4:51820",
|
||||
"public_key": "xxx..."
|
||||
}'
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# API base URL
|
||||
base_url = "http://gateway-ip:5000"
|
||||
|
||||
# Get status
|
||||
response = requests.get(f"{base_url}/api/status")
|
||||
status = response.json()
|
||||
print(f"Connected: {status['connected']}")
|
||||
|
||||
# Connect to server
|
||||
response = requests.post(
|
||||
f"{base_url}/api/connect",
|
||||
json={"server": "se-sto-wg-001"}
|
||||
)
|
||||
if response.json()["success"]:
|
||||
print("Connected successfully")
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```javascript
|
||||
// Get status
|
||||
fetch('http://gateway-ip:5000/api/status')
|
||||
.then(response => response.json())
|
||||
.then(data => console.log('Status:', data));
|
||||
|
||||
// Connect to server
|
||||
fetch('http://gateway-ip:5000/api/connect', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
server: 'se-sto-wg-001'
|
||||
})
|
||||
})
|
||||
.then(response => response.json())
|
||||
.then(data => {
|
||||
if (data.success) {
|
||||
console.log('Connected');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
API endpoints are rate-limited:
|
||||
- General endpoints: 10 requests/second
|
||||
- Connection endpoints: 5 requests/second
|
||||
|
||||
Headers returned:
|
||||
- `X-RateLimit-Limit`: Request limit
|
||||
- `X-RateLimit-Remaining`: Remaining requests
|
||||
- `X-RateLimit-Reset`: Reset timestamp
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned API features:
|
||||
- JWT authentication
|
||||
- GraphQL endpoint
|
||||
- Metrics endpoint (Prometheus format)
|
||||
- Bulk operations
|
||||
- Configuration backup/restore
|
||||
- Traffic statistics
|
||||
- Connection history
|
||||
241
docs/FAQ.md
Normal file
241
docs/FAQ.md
Normal file
|
|
@ -0,0 +1,241 @@
|
|||
# Frequently Asked Questions
|
||||
|
||||
## General Questions
|
||||
|
||||
### Q: What is the VPN Gateway?
|
||||
**A:** It's a secure VPN gateway solution that routes all network traffic through a VPN connection with a permanent killswitch to prevent leaks.
|
||||
|
||||
### Q: Which VPN providers are supported?
|
||||
**A:**
|
||||
- Mullvad VPN (commercial service)
|
||||
- Custom WireGuard servers (your own VPS)
|
||||
- Any imported WireGuard configuration
|
||||
|
||||
### Q: Can I use this with OpenVPN?
|
||||
**A:** No, this gateway only supports WireGuard protocol for better performance and security.
|
||||
|
||||
### Q: Is this free to use?
|
||||
**A:** The software is free and open source. You need to provide your own VPN service (Mullvad account or custom server).
|
||||
|
||||
## Installation
|
||||
|
||||
### Q: What are the system requirements?
|
||||
**A:**
|
||||
- LXC container or Linux system
|
||||
- Ubuntu 20.04+ or Debian 11+
|
||||
- 512MB RAM minimum
|
||||
- 1GB disk space
|
||||
- Root access
|
||||
|
||||
### Q: Can I install on a Raspberry Pi?
|
||||
**A:** Yes, as long as it runs a supported OS and has WireGuard kernel module support.
|
||||
|
||||
### Q: Does it work in Docker?
|
||||
**A:** It requires privileged mode and NET_ADMIN capability. LXC is recommended over Docker.
|
||||
|
||||
### Q: Can I install on a VPS?
|
||||
**A:** Yes, but be aware that the killswitch will block all traffic except through VPN, which might lock you out via SSH.
|
||||
|
||||
## Usage
|
||||
|
||||
### Q: No internet after disconnecting VPN?
|
||||
**A:** This is correct behavior! The killswitch blocks all internet traffic when VPN is not connected. This prevents leaks.
|
||||
|
||||
### Q: Can I disable the killswitch?
|
||||
**A:** No, the killswitch cannot be disabled through normal means. This is a security feature.
|
||||
|
||||
### Q: How do I access the WebUI?
|
||||
**A:** Navigate to `http://<container-ip>` in your browser. The WebUI is always accessible from the local network.
|
||||
|
||||
### Q: Can I use multiple VPN connections simultaneously?
|
||||
**A:** No, only one VPN connection is active at a time. You can switch between servers/providers via the WebUI.
|
||||
|
||||
## Security
|
||||
|
||||
### Q: Is this really secure?
|
||||
**A:** Yes, when properly configured:
|
||||
- Permanent killswitch prevents leaks
|
||||
- DNS leak protection enabled
|
||||
- IPv6 completely disabled
|
||||
- Continuous security monitoring
|
||||
|
||||
### Q: What about WebRTC leaks?
|
||||
**A:** WebRTC leaks are prevented at the firewall level. No direct peer connections are possible.
|
||||
|
||||
### Q: Can applications bypass the VPN?
|
||||
**A:** No, all traffic is forced through the VPN tunnel or blocked by the killswitch.
|
||||
|
||||
### Q: Is my traffic logged?
|
||||
**A:** The gateway itself doesn't log traffic. Logging depends on your VPN provider's policy.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Q: WebUI is not accessible
|
||||
**A:**
|
||||
```bash
|
||||
# Check if service is running
|
||||
sudo systemctl status vpn-webui
|
||||
|
||||
# Restart the service
|
||||
sudo systemctl restart vpn-webui
|
||||
|
||||
# Check if port is open
|
||||
sudo netstat -tlnp | grep 5000
|
||||
```
|
||||
|
||||
### Q: VPN won't connect
|
||||
**A:**
|
||||
1. Check your credentials/keys are correct
|
||||
2. Verify the server is reachable
|
||||
3. Check firewall allows outbound UDP 51820
|
||||
4. Review logs: `sudo journalctl -u vpn-webui -n 50`
|
||||
|
||||
### Q: DNS not working
|
||||
**A:**
|
||||
```bash
|
||||
# Check DNS configuration
|
||||
cat /etc/resolv.conf
|
||||
|
||||
# Test DNS resolution
|
||||
nslookup google.com
|
||||
|
||||
# Restart VPN connection
|
||||
sudo wg-quick down wg0
|
||||
sudo wg-quick up wg0
|
||||
```
|
||||
|
||||
### Q: High CPU usage
|
||||
**A:**
|
||||
- Check security monitor: `sudo systemctl status vpn-security-monitor`
|
||||
- Reduce monitoring frequency if needed
|
||||
- Check for packet loops in firewall rules
|
||||
|
||||
## Configuration
|
||||
|
||||
### Q: How do I add a custom DNS server?
|
||||
**A:** Edit the WireGuard configuration:
|
||||
```bash
|
||||
sudo nano /etc/wireguard/wg0.conf
|
||||
# Change DNS = line to your preferred servers
|
||||
```
|
||||
|
||||
### Q: Can I change the WebUI port?
|
||||
**A:** Yes, edit the systemd service:
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/vpn-webui.service
|
||||
# Change --bind 0.0.0.0:5000 to your desired port
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart vpn-webui
|
||||
```
|
||||
|
||||
### Q: How do I backup my configuration?
|
||||
**A:**
|
||||
```bash
|
||||
sudo tar czf vpn-backup.tar.gz \
|
||||
/opt/vpn-gateway \
|
||||
/etc/wireguard \
|
||||
/etc/systemd/system/vpn-*.service
|
||||
```
|
||||
|
||||
### Q: How do I enable auto-reconnect?
|
||||
**A:** Auto-reconnect is handled by the security monitor. Ensure it's running:
|
||||
```bash
|
||||
sudo systemctl enable vpn-security-monitor
|
||||
sudo systemctl start vpn-security-monitor
|
||||
```
|
||||
|
||||
## Advanced
|
||||
|
||||
### Q: Can I use split tunneling?
|
||||
**A:** Yes, for custom servers. Modify the AllowedIPs in your WireGuard config:
|
||||
```ini
|
||||
# Only specific subnets through VPN
|
||||
AllowedIPs = 10.0.0.0/8, 172.16.0.0/12
|
||||
```
|
||||
|
||||
### Q: How do I set up failover?
|
||||
**A:** Add multiple peers in the WireGuard configuration:
|
||||
```ini
|
||||
[Peer]
|
||||
# Primary
|
||||
PublicKey = xxx...
|
||||
Endpoint = primary.example.com:51820
|
||||
|
||||
[Peer]
|
||||
# Backup
|
||||
PublicKey = yyy...
|
||||
Endpoint = backup.example.com:51820
|
||||
```
|
||||
|
||||
### Q: Can I monitor traffic statistics?
|
||||
**A:**
|
||||
```bash
|
||||
# WireGuard statistics
|
||||
wg show wg0 transfer
|
||||
|
||||
# Network statistics
|
||||
vnstat -i wg0
|
||||
|
||||
# Real-time monitoring
|
||||
iftop -i wg0
|
||||
```
|
||||
|
||||
### Q: How do I integrate with existing infrastructure?
|
||||
**A:**
|
||||
- Use as default gateway for network segments
|
||||
- Configure via DHCP options
|
||||
- Set up policy-based routing for specific clients
|
||||
|
||||
## Updates
|
||||
|
||||
### Q: How do I update the VPN Gateway?
|
||||
**A:**
|
||||
```bash
|
||||
sudo /usr/local/bin/vpn-update.sh
|
||||
```
|
||||
|
||||
### Q: Will updates break my configuration?
|
||||
**A:** No, updates preserve your configuration. Backups are created automatically.
|
||||
|
||||
### Q: How do I check for updates?
|
||||
**A:**
|
||||
```bash
|
||||
# Check current version
|
||||
cat /opt/vpn-gateway/version
|
||||
|
||||
# Check for updates
|
||||
curl -s https://raw.githubusercontent.com/yourusername/vpn-gateway/main/version
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
### Q: Where can I get help?
|
||||
**A:**
|
||||
- GitHub Issues: https://github.com/yourusername/vpn-gateway/issues
|
||||
- Documentation: https://github.com/yourusername/vpn-gateway/wiki
|
||||
- Community Forum: [Link to forum]
|
||||
|
||||
### Q: How do I report a bug?
|
||||
**A:** Open an issue on GitHub with:
|
||||
- System information
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
- Relevant logs
|
||||
|
||||
### Q: Can I contribute?
|
||||
**A:** Yes! Contributions are welcome:
|
||||
- Submit pull requests
|
||||
- Report bugs
|
||||
- Improve documentation
|
||||
- Share your setup
|
||||
|
||||
## Legal
|
||||
|
||||
### Q: Is this legal to use?
|
||||
**A:** Yes, but check your local laws regarding VPN usage. Some countries restrict VPN use.
|
||||
|
||||
### Q: Can I use this commercially?
|
||||
**A:** Yes, under the MIT license terms. See LICENSE file for details.
|
||||
|
||||
### Q: What about warranty?
|
||||
**A:** This software is provided "as is" without warranty. Use at your own risk.
|
||||
339
docs/PROVIDERS.md
Normal file
339
docs/PROVIDERS.md
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
# VPN Provider Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The VPN Gateway supports three types of providers:
|
||||
1. **Mullvad VPN** - Commercial VPN service
|
||||
2. **Custom WireGuard** - Your own VPN server
|
||||
3. **Import Config** - Existing WireGuard configurations
|
||||
|
||||
## Mullvad VPN
|
||||
|
||||
### Setup
|
||||
|
||||
1. Get a Mullvad account at https://mullvad.net
|
||||
2. Note your 16-digit account number
|
||||
3. During installation, select "Mullvad" and enter your account number
|
||||
|
||||
### Features
|
||||
|
||||
- Automatic server list updates
|
||||
- 40+ countries available
|
||||
- Built-in DNS leak protection
|
||||
- No logging policy
|
||||
|
||||
### Server Selection
|
||||
|
||||
Servers are organized by:
|
||||
- **Country** (Sweden, Germany, USA, etc.)
|
||||
- **City** (Stockholm, Berlin, New York, etc.)
|
||||
- **Server** (se-sto-wg-001, de-ber-wg-002, etc.)
|
||||
|
||||
### Configuration
|
||||
|
||||
The system automatically:
|
||||
- Fetches current server list
|
||||
- Generates WireGuard keys
|
||||
- Configures DNS (100.64.0.1)
|
||||
- Sets up kill switch
|
||||
|
||||
## Custom WireGuard Server
|
||||
|
||||
### Prerequisites
|
||||
|
||||
You need:
|
||||
- A VPS or dedicated server
|
||||
- WireGuard installed on the server
|
||||
- Server public key
|
||||
- Open port (usually 51820)
|
||||
|
||||
### Server Setup (VPS Side)
|
||||
|
||||
#### 1. Install WireGuard
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install wireguard
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install wireguard-tools
|
||||
```
|
||||
|
||||
#### 2. Generate Keys
|
||||
```bash
|
||||
cd /etc/wireguard
|
||||
wg genkey | tee server_private.key | wg pubkey > server_public.key
|
||||
```
|
||||
|
||||
#### 3. Configure Server
|
||||
```bash
|
||||
cat > /etc/wireguard/wg0.conf << EOF
|
||||
[Interface]
|
||||
PrivateKey = $(cat server_private.key)
|
||||
Address = 10.0.0.1/24
|
||||
ListenPort = 51820
|
||||
|
||||
# Enable IP forwarding
|
||||
PostUp = sysctl -w net.ipv4.ip_forward=1
|
||||
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT
|
||||
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
|
||||
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT
|
||||
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
|
||||
|
||||
# Peer (VPN Gateway)
|
||||
[Peer]
|
||||
PublicKey = <GATEWAY_PUBLIC_KEY>
|
||||
AllowedIPs = 10.0.0.2/32
|
||||
EOF
|
||||
```
|
||||
|
||||
#### 4. Start WireGuard
|
||||
```bash
|
||||
sudo systemctl enable wg-quick@wg0
|
||||
sudo systemctl start wg-quick@wg0
|
||||
```
|
||||
|
||||
### Gateway Setup (Client Side)
|
||||
|
||||
During installation, provide:
|
||||
- **Endpoint**: Your server's IP:Port (e.g., 1.2.3.4:51820)
|
||||
- **Server Public Key**: From server_public.key
|
||||
- **Client IP**: Usually 10.0.0.2/32
|
||||
- **DNS**: 1.1.1.1,1.0.0.1 or your preferred DNS
|
||||
|
||||
### Adding Multiple Servers
|
||||
|
||||
Via WebUI:
|
||||
1. Go to "Custom Server" tab
|
||||
2. Click "Add New Server"
|
||||
3. Fill in server details
|
||||
4. Save configuration
|
||||
|
||||
Via API:
|
||||
```bash
|
||||
curl -X POST http://gateway-ip/api/custom/add \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "my-vps-us",
|
||||
"endpoint": "us.example.com:51820",
|
||||
"public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
|
||||
"location": "United States"
|
||||
}'
|
||||
```
|
||||
|
||||
## Import Existing Configuration
|
||||
|
||||
### Supported Formats
|
||||
|
||||
- Standard WireGuard .conf files
|
||||
- Configs from any WireGuard provider
|
||||
- Custom peer configurations
|
||||
|
||||
### Import Methods
|
||||
|
||||
#### Via WebUI
|
||||
1. Select "Import Config" tab
|
||||
2. Choose file or paste configuration
|
||||
3. Provide a name for the config
|
||||
4. Click "Import"
|
||||
|
||||
#### Via CLI
|
||||
```bash
|
||||
# Copy config to gateway
|
||||
scp myconfig.conf root@gateway-ip:/tmp/
|
||||
|
||||
# Import via API
|
||||
curl -X POST http://gateway-ip/api/import \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "imported-config",
|
||||
"config": "'"$(cat /tmp/myconfig.conf)"'"
|
||||
}'
|
||||
```
|
||||
|
||||
### Automatic Modifications
|
||||
|
||||
The system automatically:
|
||||
- Adds killswitch rules if missing
|
||||
- Preserves original settings
|
||||
- Validates configuration syntax
|
||||
|
||||
### Example Configuration
|
||||
|
||||
```ini
|
||||
[Interface]
|
||||
PrivateKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
|
||||
Address = 10.8.0.2/32
|
||||
DNS = 1.1.1.1
|
||||
|
||||
[Peer]
|
||||
PublicKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
|
||||
AllowedIPs = 0.0.0.0/0
|
||||
Endpoint = vpn.example.com:51820
|
||||
PersistentKeepalive = 25
|
||||
```
|
||||
|
||||
## Provider Switching
|
||||
|
||||
### Via WebUI
|
||||
|
||||
1. Click on provider tabs
|
||||
2. System automatically switches backend
|
||||
3. Previous provider settings are preserved
|
||||
|
||||
### Via API
|
||||
|
||||
```bash
|
||||
# Switch to Mullvad
|
||||
curl -X POST http://gateway-ip/api/provider/mullvad
|
||||
|
||||
# Switch to Custom
|
||||
curl -X POST http://gateway-ip/api/provider/custom
|
||||
|
||||
# Switch to Imported
|
||||
curl -X POST http://gateway-ip/api/provider/imported
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Split Tunneling
|
||||
|
||||
For custom servers, modify AllowedIPs:
|
||||
```ini
|
||||
# Route only specific subnets through VPN
|
||||
AllowedIPs = 10.0.0.0/8, 192.168.0.0/16
|
||||
|
||||
# Route everything except local network
|
||||
AllowedIPs = 0.0.0.0/1, 128.0.0.0/1
|
||||
```
|
||||
|
||||
### Multiple Peers (Failover)
|
||||
|
||||
```ini
|
||||
[Peer]
|
||||
# Primary server
|
||||
PublicKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
|
||||
AllowedIPs = 0.0.0.0/0
|
||||
Endpoint = primary.example.com:51820
|
||||
|
||||
[Peer]
|
||||
# Backup server
|
||||
PublicKey = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy=
|
||||
AllowedIPs = 0.0.0.0/0
|
||||
Endpoint = backup.example.com:51820
|
||||
```
|
||||
|
||||
### Custom DNS
|
||||
|
||||
Modify DNS in the configuration:
|
||||
```ini
|
||||
# CloudFlare
|
||||
DNS = 1.1.1.1, 1.0.0.1
|
||||
|
||||
# Quad9
|
||||
DNS = 9.9.9.9, 149.112.112.112
|
||||
|
||||
# Custom/Local
|
||||
DNS = 192.168.1.1
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### MTU Settings
|
||||
|
||||
For optimal performance:
|
||||
```ini
|
||||
[Interface]
|
||||
MTU = 1420 # Default, works for most connections
|
||||
# MTU = 1380 # For problematic connections
|
||||
# MTU = 1280 # Maximum compatibility
|
||||
```
|
||||
|
||||
### Persistent Keepalive
|
||||
|
||||
Adjust based on your needs:
|
||||
```ini
|
||||
# For stable connections
|
||||
PersistentKeepalive = 25
|
||||
|
||||
# For NAT/firewall traversal
|
||||
PersistentKeepalive = 10
|
||||
|
||||
# Disable for on-demand
|
||||
# PersistentKeepalive = 0
|
||||
```
|
||||
|
||||
## Troubleshooting Providers
|
||||
|
||||
### Mullvad Issues
|
||||
|
||||
```bash
|
||||
# Check account status
|
||||
curl https://api.mullvad.net/www/accounts/<account-number>/
|
||||
|
||||
# Test server connectivity
|
||||
ping -c 1 <server-ip>
|
||||
|
||||
# Verify WireGuard keys
|
||||
wg show wg0 public-key
|
||||
```
|
||||
|
||||
### Custom Server Issues
|
||||
|
||||
```bash
|
||||
# Test connectivity
|
||||
nc -zv <server-ip> 51820
|
||||
|
||||
# Check server logs (on VPS)
|
||||
sudo journalctl -u wg-quick@wg0 -f
|
||||
|
||||
# Verify keys match
|
||||
echo "<public-key>" | base64 -d | wc -c # Should be 32
|
||||
```
|
||||
|
||||
### Import Issues
|
||||
|
||||
```bash
|
||||
# Validate config syntax
|
||||
wg-quick strip /path/to/config.conf
|
||||
|
||||
# Test config manually
|
||||
sudo wg-quick up /tmp/test.conf
|
||||
sudo wg-quick down /tmp/test.conf
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Key Management
|
||||
|
||||
- Never share private keys
|
||||
- Rotate keys periodically
|
||||
- Use unique keys per device/gateway
|
||||
|
||||
### Server Hardening
|
||||
|
||||
For custom servers:
|
||||
```bash
|
||||
# Firewall rules
|
||||
ufw allow 51820/udp
|
||||
ufw allow from 10.0.0.0/24
|
||||
|
||||
# Disable password auth
|
||||
sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
|
||||
|
||||
# Enable automatic updates
|
||||
apt install unattended-upgrades
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
```bash
|
||||
# Connection status
|
||||
wg show
|
||||
|
||||
# Traffic statistics
|
||||
wg show wg0 transfer
|
||||
|
||||
# Active connections
|
||||
netstat -tunlp | grep 51820
|
||||
```
|
||||
211
docs/QUICKSTART.md
Normal file
211
docs/QUICKSTART.md
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
# Quick Start Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- LXC Container with Ubuntu/Debian
|
||||
- Root access
|
||||
- Internet connection for initial setup
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. One-Line Install
|
||||
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 2. Manual Install
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/yourusername/vpn-gateway.git
|
||||
cd vpn-gateway
|
||||
|
||||
# Run installer
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
## Initial Setup
|
||||
|
||||
### Step 1: Network Detection
|
||||
|
||||
The installer will auto-detect your network configuration:
|
||||
- Network interface (e.g., eth0)
|
||||
- LAN subnet (e.g., 192.168.1.0/24)
|
||||
- Container IP address
|
||||
|
||||
Confirm or modify as needed.
|
||||
|
||||
### Step 2: Choose Provider
|
||||
|
||||
Select your VPN provider:
|
||||
|
||||
#### Option 1: Mullvad VPN
|
||||
```
|
||||
Select provider [1-3]: 1
|
||||
Enter your Mullvad account number: 1234567890123456
|
||||
```
|
||||
|
||||
#### Option 2: Custom WireGuard Server
|
||||
```
|
||||
Select provider [1-3]: 2
|
||||
Server endpoint (IP:Port): 1.2.3.4:51820
|
||||
Server public key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
|
||||
```
|
||||
|
||||
#### Option 3: Import Configuration
|
||||
```
|
||||
Select provider [1-3]: 3
|
||||
Path to WireGuard config: /path/to/config.conf
|
||||
```
|
||||
|
||||
### Step 3: Complete Installation
|
||||
|
||||
The installer will:
|
||||
1. Install dependencies
|
||||
2. Configure killswitch
|
||||
3. Set up WebUI
|
||||
4. Start services
|
||||
|
||||
## Using the WebUI
|
||||
|
||||
### Access the Interface
|
||||
|
||||
Open your browser and navigate to:
|
||||
```
|
||||
http://<container-ip>
|
||||
```
|
||||
|
||||
### Connect to VPN
|
||||
|
||||
1. **Select Location** (Mullvad only)
|
||||
- Choose country
|
||||
- Choose city
|
||||
- Choose server
|
||||
|
||||
2. **Click Connect**
|
||||
- Connection established in ~2-5 seconds
|
||||
- Status indicator turns green
|
||||
|
||||
3. **Verify Connection**
|
||||
- Check public IP displayed
|
||||
- Verify location shown
|
||||
|
||||
### Disconnect from VPN
|
||||
|
||||
1. Click **Disconnect** button
|
||||
2. **WARNING**: No internet access after disconnect (killswitch active)
|
||||
|
||||
## Client Configuration
|
||||
|
||||
### Configure Your Devices
|
||||
|
||||
Set on each client device:
|
||||
|
||||
#### Windows
|
||||
1. Network Settings → IPv4 Properties
|
||||
2. Default Gateway: `<container-ip>`
|
||||
3. DNS Server: `<container-ip>` or `1.1.1.1`
|
||||
|
||||
#### Linux
|
||||
```bash
|
||||
# Temporary
|
||||
sudo ip route del default
|
||||
sudo ip route add default via <container-ip>
|
||||
echo "nameserver <container-ip>" | sudo tee /etc/resolv.conf
|
||||
|
||||
# Permanent (NetworkManager)
|
||||
nmcli connection modify <connection-name> ipv4.gateway <container-ip>
|
||||
nmcli connection modify <connection-name> ipv4.dns <container-ip>
|
||||
```
|
||||
|
||||
#### macOS
|
||||
1. System Preferences → Network
|
||||
2. Advanced → TCP/IP
|
||||
3. Router: `<container-ip>`
|
||||
4. DNS: `<container-ip>`
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Check Status
|
||||
```bash
|
||||
# Service status
|
||||
sudo systemctl status vpn-webui
|
||||
|
||||
# Connection status
|
||||
curl http://localhost:5000/api/status
|
||||
|
||||
# Health check
|
||||
sudo /usr/local/bin/vpn-health-check.sh
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# All logs
|
||||
sudo journalctl -u vpn-webui -u vpn-killswitch -f
|
||||
|
||||
# WebUI logs only
|
||||
sudo journalctl -u vpn-webui -f
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
```bash
|
||||
sudo systemctl restart vpn-webui
|
||||
sudo systemctl restart vpn-security-monitor
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
⚠️ **Killswitch Always Active**
|
||||
- No internet without VPN connection
|
||||
- This is intentional for security
|
||||
- Local network still accessible
|
||||
|
||||
⚠️ **After Disconnect**
|
||||
- Internet blocked until reconnection
|
||||
- WebUI remains accessible
|
||||
- Connect to VPN to restore internet
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### WebUI Not Accessible
|
||||
```bash
|
||||
# Check if service is running
|
||||
sudo systemctl status vpn-webui
|
||||
|
||||
# Check if port is listening
|
||||
sudo netstat -tlnp | grep 5000
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart vpn-webui
|
||||
```
|
||||
|
||||
### No Internet After Connect
|
||||
```bash
|
||||
# Check VPN status
|
||||
sudo wg show
|
||||
|
||||
# Check killswitch
|
||||
sudo iptables -L -n -v
|
||||
|
||||
# Check DNS
|
||||
nslookup google.com
|
||||
```
|
||||
|
||||
### Can't Connect to VPN
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u vpn-webui -n 50
|
||||
|
||||
# Test killswitch
|
||||
sudo /usr/local/bin/vpn-killswitch.sh verify
|
||||
|
||||
# Manual connection test
|
||||
sudo wg-quick up wg0
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read [Provider Configuration](PROVIDERS.md) for advanced setup
|
||||
- Review [Security Documentation](SECURITY.md) for security features
|
||||
- See [FAQ](FAQ.md) for common questions
|
||||
77
docs/README.md
Normal file
77
docs/README.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# VPN Gateway Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation covers the VPN Gateway multi-provider system with permanent killswitch protection.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Quick Start Guide](QUICKSTART.md) - Get up and running in minutes
|
||||
- [Provider Configuration](PROVIDERS.md) - Detailed provider setup
|
||||
- [Security Documentation](SECURITY.md) - Security features and best practices
|
||||
- [API Reference](API.md) - WebUI API endpoints
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
|
||||
- [FAQ](FAQ.md) - Frequently asked questions
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Client Devices │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ VPN Gateway Container │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ WebUI (Port 80/5000) │ │
|
||||
│ └──────────┬──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼──────────────────┐ │
|
||||
│ │ Flask Backend (Python) │ │
|
||||
│ └──────────┬──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼──────────────────┐ │
|
||||
│ │ WireGuard Interface (wg0) │ │
|
||||
│ └──────────┬──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼──────────────────┐ │
|
||||
│ │ Killswitch (iptables) │ │
|
||||
│ └──────────┬──────────────────┘ │
|
||||
└─────────────┼───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ VPN Provider │
|
||||
│ • Mullvad │
|
||||
│ • Custom Server │
|
||||
│ • Imported Config│
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### 1. Killswitch
|
||||
- Permanent firewall rules
|
||||
- Blocks all non-VPN traffic
|
||||
- Cannot be disabled via UI
|
||||
|
||||
### 2. WebUI
|
||||
- Modern responsive interface
|
||||
- Real-time status monitoring
|
||||
- Multi-provider support
|
||||
|
||||
### 3. Backend
|
||||
- Flask-based API
|
||||
- Provider management
|
||||
- Connection handling
|
||||
|
||||
### 4. Security Monitor
|
||||
- Continuous monitoring
|
||||
- Leak detection
|
||||
- Auto-recovery
|
||||
|
||||
## Support
|
||||
|
||||
- GitHub Issues: https://github.com/yourusername/vpn-gateway/issues
|
||||
- Documentation: https://github.com/yourusername/vpn-gateway/wiki
|
||||
404
docs/SECURITY.md
Normal file
404
docs/SECURITY.md
Normal file
|
|
@ -0,0 +1,404 @@
|
|||
# Security Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The VPN Gateway implements multiple layers of security to ensure zero-leak protection and maintain privacy.
|
||||
|
||||
## Core Security Features
|
||||
|
||||
### 1. Permanent Killswitch
|
||||
|
||||
The killswitch is the primary security mechanism that prevents any traffic leaks.
|
||||
|
||||
#### Implementation
|
||||
|
||||
- **Firewall Rules**: Default DROP policy for all chains
|
||||
- **Boot Protection**: Activates before network initialization
|
||||
- **Cannot be Disabled**: No UI or API endpoint to disable
|
||||
- **Continuous Monitoring**: Verified every 10 seconds
|
||||
|
||||
#### Technical Details
|
||||
|
||||
```bash
|
||||
# Default policies
|
||||
iptables -P INPUT DROP
|
||||
iptables -P FORWARD DROP
|
||||
iptables -P OUTPUT DROP
|
||||
|
||||
# Only allowed traffic:
|
||||
# - Loopback (system operations)
|
||||
# - LAN subnet (WebUI access)
|
||||
# - Established connections
|
||||
# - VPN tunnel (when active)
|
||||
```
|
||||
|
||||
### 2. DNS Leak Protection
|
||||
|
||||
#### Mechanisms
|
||||
|
||||
1. **Forced VPN DNS**: All DNS queries routed through VPN
|
||||
2. **System DNS Override**: /etc/resolv.conf locked
|
||||
3. **IPv6 Disabled**: Prevents IPv6 DNS leaks
|
||||
4. **DNS Filtering**: Only root can make DNS queries for VPN connection
|
||||
|
||||
#### Configuration
|
||||
|
||||
```bash
|
||||
# DNS through VPN only
|
||||
iptables -A OUTPUT -p udp --dport 53 -m owner --uid-owner root -j ACCEPT
|
||||
iptables -A OUTPUT -p tcp --dport 53 -m owner --uid-owner root -j ACCEPT
|
||||
|
||||
# Block all other DNS
|
||||
iptables -A OUTPUT -p udp --dport 53 -j DROP
|
||||
iptables -A OUTPUT -p tcp --dport 53 -j DROP
|
||||
```
|
||||
|
||||
### 3. IPv6 Protection
|
||||
|
||||
Complete IPv6 blocking to prevent leaks:
|
||||
|
||||
```bash
|
||||
# IPv6 firewall
|
||||
ip6tables -P INPUT DROP
|
||||
ip6tables -P FORWARD DROP
|
||||
ip6tables -P OUTPUT DROP
|
||||
|
||||
# Kernel level
|
||||
sysctl -w net.ipv6.conf.all.disable_ipv6=1
|
||||
sysctl -w net.ipv6.conf.default.disable_ipv6=1
|
||||
```
|
||||
|
||||
### 4. Security Monitor
|
||||
|
||||
Continuous monitoring daemon that:
|
||||
- Verifies killswitch every 10 seconds
|
||||
- Detects potential leaks
|
||||
- Auto-recovers from failures
|
||||
- Logs security events
|
||||
|
||||
## Threat Model
|
||||
|
||||
### Protected Against
|
||||
|
||||
✅ **IP Leaks**
|
||||
- Killswitch blocks all non-VPN traffic
|
||||
- No traffic possible without active tunnel
|
||||
|
||||
✅ **DNS Leaks**
|
||||
- All DNS through VPN
|
||||
- System DNS locked
|
||||
- IPv6 DNS blocked
|
||||
|
||||
✅ **WebRTC Leaks**
|
||||
- Blocked at firewall level
|
||||
- No direct peer connections
|
||||
|
||||
✅ **IPv6 Leaks**
|
||||
- IPv6 completely disabled
|
||||
- Both firewall and kernel level
|
||||
|
||||
✅ **Connection Drops**
|
||||
- Killswitch remains active
|
||||
- No traffic during reconnection
|
||||
- Auto-recovery available
|
||||
|
||||
✅ **Malicious Applications**
|
||||
- Cannot bypass firewall rules
|
||||
- All traffic subject to killswitch
|
||||
|
||||
### Not Protected Against
|
||||
|
||||
❌ **Compromised Container**
|
||||
- If attacker gains root access
|
||||
- Can modify firewall rules
|
||||
|
||||
❌ **Host System Compromise**
|
||||
- Container isolation breach
|
||||
- Hypervisor vulnerabilities
|
||||
|
||||
❌ **Traffic Analysis**
|
||||
- VPN traffic patterns visible
|
||||
- Timing correlation attacks
|
||||
|
||||
❌ **VPN Provider Compromise**
|
||||
- Malicious VPN server
|
||||
- Provider logging (choose carefully)
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### 1. Installation Security
|
||||
|
||||
```bash
|
||||
# Verify installer integrity
|
||||
sha256sum install.sh
|
||||
# Compare with published hash
|
||||
|
||||
# Review script before execution
|
||||
less install.sh
|
||||
|
||||
# Run with specific version
|
||||
curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/v1.0.0/install.sh | bash
|
||||
```
|
||||
|
||||
### 2. Access Control
|
||||
|
||||
#### WebUI Protection
|
||||
|
||||
```nginx
|
||||
# Restrict WebUI access to LAN only
|
||||
location / {
|
||||
allow 192.168.1.0/24;
|
||||
deny all;
|
||||
# ... proxy settings
|
||||
}
|
||||
```
|
||||
|
||||
#### SSH Hardening
|
||||
|
||||
```bash
|
||||
# Disable password authentication
|
||||
PasswordAuthentication no
|
||||
|
||||
# Key-only access
|
||||
PubkeyAuthentication yes
|
||||
|
||||
# Restrict to specific IPs
|
||||
AllowUsers root@192.168.1.0/24
|
||||
```
|
||||
|
||||
### 3. Key Management
|
||||
|
||||
#### WireGuard Keys
|
||||
|
||||
```bash
|
||||
# Generate new keys periodically
|
||||
wg genkey | tee privatekey | wg pubkey > publickey
|
||||
|
||||
# Secure storage
|
||||
chmod 600 /etc/wireguard/*.key
|
||||
|
||||
# Never share private keys
|
||||
# Unique keys per gateway
|
||||
```
|
||||
|
||||
#### Rotation Schedule
|
||||
|
||||
- **Private Keys**: Every 3-6 months
|
||||
- **Preshared Keys**: Every 1-3 months
|
||||
- **API Keys**: Every 30 days
|
||||
|
||||
### 4. Monitoring
|
||||
|
||||
#### Security Logs
|
||||
|
||||
```bash
|
||||
# Monitor security events
|
||||
journalctl -u vpn-security-monitor -f
|
||||
|
||||
# Check for failures
|
||||
grep "ALERT\|ERROR" /var/log/vpn-security-monitor.log
|
||||
|
||||
# Audit firewall drops
|
||||
iptables -L -n -v | grep DROP
|
||||
```
|
||||
|
||||
#### Leak Testing
|
||||
|
||||
```bash
|
||||
# Regular leak tests
|
||||
curl https://ipleak.net/json/
|
||||
curl https://am.i.mullvad.net/json
|
||||
|
||||
# DNS leak test
|
||||
nslookup example.com
|
||||
dig example.com
|
||||
```
|
||||
|
||||
### 5. Updates
|
||||
|
||||
#### Security Updates
|
||||
|
||||
```bash
|
||||
# System updates (through VPN)
|
||||
apt update && apt upgrade
|
||||
|
||||
# VPN Gateway updates
|
||||
/usr/local/bin/vpn-update.sh
|
||||
|
||||
# Check for security advisories
|
||||
```
|
||||
|
||||
#### Automatic Updates
|
||||
|
||||
```bash
|
||||
# Enable unattended upgrades
|
||||
apt install unattended-upgrades
|
||||
dpkg-reconfigure -plow unattended-upgrades
|
||||
```
|
||||
|
||||
## Incident Response
|
||||
|
||||
### 1. Leak Detected
|
||||
|
||||
If a leak is detected:
|
||||
|
||||
1. **Immediate Action**
|
||||
```bash
|
||||
# Re-enable killswitch
|
||||
/usr/local/bin/vpn-killswitch.sh enable
|
||||
|
||||
# Disconnect VPN
|
||||
wg-quick down wg0
|
||||
```
|
||||
|
||||
2. **Investigation**
|
||||
```bash
|
||||
# Check logs
|
||||
journalctl -u vpn-security-monitor -n 100
|
||||
|
||||
# Verify firewall rules
|
||||
iptables -L -n -v
|
||||
```
|
||||
|
||||
3. **Recovery**
|
||||
```bash
|
||||
# Restart security services
|
||||
systemctl restart vpn-killswitch
|
||||
systemctl restart vpn-security-monitor
|
||||
```
|
||||
|
||||
### 2. Suspicious Activity
|
||||
|
||||
Signs of compromise:
|
||||
- Unexpected firewall rule changes
|
||||
- Unknown processes with network access
|
||||
- Unusual CPU/memory usage
|
||||
- Modified system files
|
||||
|
||||
Response:
|
||||
```bash
|
||||
# Check processes
|
||||
netstat -tulpn
|
||||
ps aux | grep -v grep | grep wg
|
||||
|
||||
# Check file integrity
|
||||
debsums -c
|
||||
find /etc -type f -mtime -1
|
||||
|
||||
# Review auth logs
|
||||
grep "Failed\|Invalid" /var/log/auth.log
|
||||
```
|
||||
|
||||
### 3. Emergency Shutdown
|
||||
|
||||
If immediate isolation needed:
|
||||
|
||||
```bash
|
||||
# Block ALL network traffic
|
||||
iptables -P INPUT DROP
|
||||
iptables -P OUTPUT DROP
|
||||
iptables -P FORWARD DROP
|
||||
iptables -F
|
||||
|
||||
# Stop services
|
||||
systemctl stop vpn-webui
|
||||
systemctl stop wg-quick@wg0
|
||||
|
||||
# Preserve evidence
|
||||
tar czf /tmp/evidence-$(date +%s).tar.gz \
|
||||
/var/log \
|
||||
/etc/wireguard \
|
||||
/opt/vpn-gateway/logs
|
||||
```
|
||||
|
||||
## Security Hardening
|
||||
|
||||
### 1. Container Hardening
|
||||
|
||||
```bash
|
||||
# Limit capabilities
|
||||
lxc config set <container> security.nesting false
|
||||
lxc config set <container> security.privileged false
|
||||
|
||||
# Resource limits
|
||||
lxc config set <container> limits.memory 512MB
|
||||
lxc config set <container> limits.cpu 1
|
||||
```
|
||||
|
||||
### 2. Network Hardening
|
||||
|
||||
```bash
|
||||
# Rate limiting
|
||||
iptables -A INPUT -p tcp --dport 5000 \
|
||||
-m conntrack --ctstate NEW \
|
||||
-m limit --limit 10/min --limit-burst 5 \
|
||||
-j ACCEPT
|
||||
|
||||
# SYN flood protection
|
||||
echo 1 > /proc/sys/net/ipv4/tcp_syncookies
|
||||
echo 2048 > /proc/sys/net/ipv4/tcp_max_syn_backlog
|
||||
```
|
||||
|
||||
### 3. Application Hardening
|
||||
|
||||
```python
|
||||
# Flask security headers
|
||||
from flask import Flask
|
||||
from flask_talisman import Talisman
|
||||
|
||||
app = Flask(__name__)
|
||||
Talisman(app,
|
||||
force_https=False, # Handle at reverse proxy
|
||||
strict_transport_security=True,
|
||||
content_security_policy={
|
||||
'default-src': "'self'"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Compliance
|
||||
|
||||
### GDPR Compliance
|
||||
|
||||
- No personal data logging
|
||||
- User control over data
|
||||
- Right to deletion
|
||||
- Transparent processing
|
||||
|
||||
### Security Standards
|
||||
|
||||
- CIS Benchmarks compliance
|
||||
- NIST framework alignment
|
||||
- Zero-trust architecture
|
||||
- Defense in depth
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Daily
|
||||
- [ ] Check service status
|
||||
- [ ] Review security logs
|
||||
- [ ] Verify killswitch active
|
||||
|
||||
### Weekly
|
||||
- [ ] Run leak tests
|
||||
- [ ] Check for updates
|
||||
- [ ] Review firewall rules
|
||||
|
||||
### Monthly
|
||||
- [ ] Rotate keys
|
||||
- [ ] Audit access logs
|
||||
- [ ] Update documentation
|
||||
|
||||
### Quarterly
|
||||
- [ ] Security assessment
|
||||
- [ ] Penetration testing
|
||||
- [ ] Disaster recovery test
|
||||
|
||||
## Contact
|
||||
|
||||
For security issues:
|
||||
- **Email**: security@yourdomain.com
|
||||
- **PGP Key**: [Public key]
|
||||
- **Response Time**: < 24 hours for critical issues
|
||||
|
||||
Please report security vulnerabilities responsibly.
|
||||
425
docs/TROUBLESHOOTING.md
Normal file
425
docs/TROUBLESHOOTING.md
Normal file
|
|
@ -0,0 +1,425 @@
|
|||
# Troubleshooting Guide
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Installation Issues
|
||||
|
||||
#### Problem: Installation fails with dependency errors
|
||||
```bash
|
||||
E: Unable to locate package wireguard
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Update package lists
|
||||
sudo apt update
|
||||
|
||||
# Enable backports (Debian)
|
||||
echo "deb http://deb.debian.org/debian $(lsb_release -cs)-backports main" | \
|
||||
sudo tee /etc/apt/sources.list.d/backports.list
|
||||
sudo apt update
|
||||
|
||||
# Install kernel headers
|
||||
sudo apt install linux-headers-$(uname -r)
|
||||
|
||||
# Retry installation
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
#### Problem: WireGuard module not loading
|
||||
```bash
|
||||
modprobe: FATAL: Module wireguard not found
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Install WireGuard kernel module
|
||||
sudo apt install wireguard-dkms
|
||||
|
||||
# Load module manually
|
||||
sudo modprobe wireguard
|
||||
|
||||
# Verify module loaded
|
||||
lsmod | grep wireguard
|
||||
```
|
||||
|
||||
### Connection Issues
|
||||
|
||||
#### Problem: VPN won't connect
|
||||
**Symptoms:** Connection timeout, no handshake
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check server reachability:**
|
||||
```bash
|
||||
# Ping server (if ICMP allowed)
|
||||
ping -c 3 <server-ip>
|
||||
|
||||
# Check port connectivity
|
||||
nc -zv <server-ip> 51820
|
||||
|
||||
# Trace route
|
||||
traceroute <server-ip>
|
||||
```
|
||||
|
||||
2. **Verify credentials:**
|
||||
```bash
|
||||
# Check keys format
|
||||
wg show wg0 private-key
|
||||
wg show wg0 public-key
|
||||
|
||||
# Verify key length (should be 44 characters)
|
||||
echo "<key>" | wc -c
|
||||
```
|
||||
|
||||
3. **Check firewall:**
|
||||
```bash
|
||||
# Ensure UDP 51820 outbound is allowed
|
||||
sudo iptables -L OUTPUT -n -v | grep 51820
|
||||
|
||||
# Temporarily allow all outbound (testing only!)
|
||||
sudo iptables -I OUTPUT 1 -j ACCEPT
|
||||
```
|
||||
|
||||
4. **Review logs:**
|
||||
```bash
|
||||
# Check WebUI logs
|
||||
sudo journalctl -u vpn-webui -n 100
|
||||
|
||||
# Check WireGuard logs
|
||||
sudo dmesg | grep wireguard
|
||||
|
||||
# Enable debug logging
|
||||
echo 'module wireguard +p' | sudo tee /sys/kernel/debug/dynamic_debug/control
|
||||
```
|
||||
|
||||
#### Problem: Connection drops frequently
|
||||
**Symptoms:** Intermittent connectivity, handshake failures
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Adjust keepalive:**
|
||||
```bash
|
||||
# Edit WireGuard config
|
||||
sudo nano /etc/wireguard/wg0.conf
|
||||
|
||||
# Reduce keepalive interval
|
||||
PersistentKeepalive = 10 # Instead of 25
|
||||
```
|
||||
|
||||
2. **Check MTU:**
|
||||
```bash
|
||||
# Test different MTU values
|
||||
sudo ip link set dev wg0 mtu 1380
|
||||
|
||||
# Find optimal MTU
|
||||
ping -M do -s 1372 <vpn-server-ip>
|
||||
# Increase/decrease -s value until it works
|
||||
```
|
||||
|
||||
3. **Monitor connection:**
|
||||
```bash
|
||||
# Watch handshakes
|
||||
watch -n 1 'wg show wg0 latest-handshakes'
|
||||
|
||||
# Check for packet loss
|
||||
mtr <vpn-server-ip>
|
||||
```
|
||||
|
||||
### Network Issues
|
||||
|
||||
#### Problem: No internet after connecting
|
||||
**Symptoms:** VPN connected but can't browse
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check routing:**
|
||||
```bash
|
||||
# Show routing table
|
||||
ip route show
|
||||
|
||||
# Verify default route through VPN
|
||||
ip route | grep default
|
||||
|
||||
# Add route manually if missing
|
||||
sudo ip route add default dev wg0
|
||||
```
|
||||
|
||||
2. **Check DNS:**
|
||||
```bash
|
||||
# Test DNS resolution
|
||||
nslookup google.com
|
||||
dig google.com
|
||||
|
||||
# Check DNS config
|
||||
cat /etc/resolv.conf
|
||||
|
||||
# Force DNS update
|
||||
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
|
||||
```
|
||||
|
||||
3. **Check NAT:**
|
||||
```bash
|
||||
# Verify NAT rules
|
||||
sudo iptables -t nat -L POSTROUTING -n -v
|
||||
|
||||
# Add NAT manually if missing
|
||||
sudo iptables -t nat -A POSTROUTING -o wg0 -j MASQUERADE
|
||||
```
|
||||
|
||||
#### Problem: Local network not accessible
|
||||
**Symptoms:** Can't reach LAN devices when VPN connected
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Add LAN route exception
|
||||
sudo ip route add 192.168.1.0/24 dev eth0
|
||||
|
||||
# Or modify WireGuard AllowedIPs
|
||||
# Change from: 0.0.0.0/0
|
||||
# To: 0.0.0.0/1, 128.0.0.0/1
|
||||
```
|
||||
|
||||
### WebUI Issues
|
||||
|
||||
#### Problem: WebUI not loading
|
||||
**Symptoms:** Connection refused, timeout
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check service status:**
|
||||
```bash
|
||||
# Service status
|
||||
sudo systemctl status vpn-webui
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart vpn-webui
|
||||
|
||||
# Check if running
|
||||
ps aux | grep gunicorn
|
||||
```
|
||||
|
||||
2. **Check port binding:**
|
||||
```bash
|
||||
# Verify port is listening
|
||||
sudo netstat -tlnp | grep 5000
|
||||
sudo ss -tlnp | grep 5000
|
||||
|
||||
# Check for port conflicts
|
||||
sudo lsof -i :5000
|
||||
```
|
||||
|
||||
3. **Check Nginx (if used):**
|
||||
```bash
|
||||
# Test Nginx config
|
||||
sudo nginx -t
|
||||
|
||||
# Restart Nginx
|
||||
sudo systemctl restart nginx
|
||||
|
||||
# Check Nginx logs
|
||||
sudo tail -f /var/log/nginx/error.log
|
||||
```
|
||||
|
||||
#### Problem: Can't change settings
|
||||
**Symptoms:** Changes don't save, errors on submit
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check permissions:**
|
||||
```bash
|
||||
# Fix ownership
|
||||
sudo chown -R root:root /opt/vpn-gateway
|
||||
|
||||
# Fix permissions
|
||||
sudo chmod 755 /opt/vpn-gateway
|
||||
sudo chmod 644 /opt/vpn-gateway/app.py
|
||||
```
|
||||
|
||||
2. **Check disk space:**
|
||||
```bash
|
||||
# Check available space
|
||||
df -h /opt/vpn-gateway
|
||||
|
||||
# Clean up if needed
|
||||
sudo journalctl --vacuum-time=7d
|
||||
sudo apt clean
|
||||
```
|
||||
|
||||
### Security Issues
|
||||
|
||||
#### Problem: Killswitch not working
|
||||
**Symptoms:** Internet accessible without VPN
|
||||
|
||||
**CRITICAL - Fix immediately:**
|
||||
|
||||
1. **Re-enable killswitch:**
|
||||
```bash
|
||||
# Force enable
|
||||
sudo /usr/local/bin/vpn-killswitch.sh enable
|
||||
|
||||
# Verify rules
|
||||
sudo iptables -L -n -v | grep DROP
|
||||
```
|
||||
|
||||
2. **Check for rule conflicts:**
|
||||
```bash
|
||||
# List all rules
|
||||
sudo iptables-save
|
||||
|
||||
# Remove conflicting rules
|
||||
sudo iptables -F OUTPUT
|
||||
sudo iptables -P OUTPUT DROP
|
||||
```
|
||||
|
||||
3. **Restart security monitor:**
|
||||
```bash
|
||||
sudo systemctl restart vpn-security-monitor
|
||||
sudo systemctl status vpn-security-monitor
|
||||
```
|
||||
|
||||
#### Problem: DNS leaks detected
|
||||
**Symptoms:** DNS queries not going through VPN
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Force VPN DNS:**
|
||||
```bash
|
||||
# Lock resolv.conf
|
||||
sudo chattr +i /etc/resolv.conf
|
||||
|
||||
# Disable systemd-resolved
|
||||
sudo systemctl stop systemd-resolved
|
||||
sudo systemctl disable systemd-resolved
|
||||
```
|
||||
|
||||
2. **Check firewall rules:**
|
||||
```bash
|
||||
# Block DNS except through VPN
|
||||
sudo iptables -A OUTPUT -p udp --dport 53 ! -o wg0 -j DROP
|
||||
sudo iptables -A OUTPUT -p tcp --dport 53 ! -o wg0 -j DROP
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
#### Problem: Slow speeds
|
||||
**Symptoms:** Poor throughput, high latency
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Optimize MTU:**
|
||||
```bash
|
||||
# Test optimal MTU
|
||||
for mtu in 1420 1400 1380 1360; do
|
||||
sudo ip link set dev wg0 mtu $mtu
|
||||
echo "Testing MTU $mtu"
|
||||
iperf3 -c <server-ip> -t 5
|
||||
done
|
||||
```
|
||||
|
||||
2. **Check CPU usage:**
|
||||
```bash
|
||||
# Monitor CPU
|
||||
top -n 1 | grep -E "wireguard|python"
|
||||
|
||||
# Check interrupts
|
||||
watch -n 1 'cat /proc/interrupts | grep -E "eth|wg"'
|
||||
```
|
||||
|
||||
3. **Tune kernel parameters:**
|
||||
```bash
|
||||
# Optimize network stack
|
||||
cat >> /etc/sysctl.conf << EOF
|
||||
net.core.rmem_max = 134217728
|
||||
net.core.wmem_max = 134217728
|
||||
net.ipv4.tcp_rmem = 4096 87380 134217728
|
||||
net.ipv4.tcp_wmem = 4096 65536 134217728
|
||||
net.core.netdev_max_backlog = 30000
|
||||
net.ipv4.tcp_congestion_control = bbr
|
||||
EOF
|
||||
|
||||
sudo sysctl -p
|
||||
```
|
||||
|
||||
### Diagnostic Commands
|
||||
|
||||
#### Complete System Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "=== VPN Gateway Diagnostics ==="
|
||||
echo ""
|
||||
echo "1. Services Status:"
|
||||
systemctl status vpn-webui --no-pager | head -n 10
|
||||
systemctl status vpn-killswitch --no-pager | head -n 10
|
||||
systemctl status vpn-security-monitor --no-pager | head -n 10
|
||||
echo ""
|
||||
echo "2. VPN Status:"
|
||||
wg show
|
||||
echo ""
|
||||
echo "3. Firewall Rules:"
|
||||
iptables -L -n | head -n 20
|
||||
echo ""
|
||||
echo "4. Network Configuration:"
|
||||
ip addr show
|
||||
ip route show
|
||||
echo ""
|
||||
echo "5. DNS Configuration:"
|
||||
cat /etc/resolv.conf
|
||||
echo ""
|
||||
echo "6. Recent Logs:"
|
||||
journalctl -u vpn-webui -n 20 --no-pager
|
||||
echo ""
|
||||
echo "7. Disk Usage:"
|
||||
df -h /opt/vpn-gateway
|
||||
echo ""
|
||||
echo "8. Memory Usage:"
|
||||
free -h
|
||||
```
|
||||
|
||||
#### Export Debug Info
|
||||
```bash
|
||||
# Create debug archive
|
||||
sudo tar czf vpn-debug-$(date +%s).tar.gz \
|
||||
/var/log/vpn-*.log \
|
||||
/var/log/syslog \
|
||||
/etc/wireguard/ \
|
||||
/opt/vpn-gateway/logs/ \
|
||||
<(iptables-save) \
|
||||
<(wg show) \
|
||||
<(ip addr) \
|
||||
<(ip route) \
|
||||
<(systemctl status vpn-*)
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
If problems persist:
|
||||
|
||||
1. **Check logs thoroughly:**
|
||||
```bash
|
||||
sudo journalctl -xe
|
||||
sudo dmesg | tail -50
|
||||
```
|
||||
|
||||
2. **Run health check:**
|
||||
```bash
|
||||
sudo /usr/local/bin/vpn-health-check.sh
|
||||
```
|
||||
|
||||
3. **Create issue on GitHub** with:
|
||||
- System info: `uname -a`
|
||||
- Service status: `systemctl status vpn-*`
|
||||
- Error messages
|
||||
- Debug archive
|
||||
|
||||
4. **Emergency recovery:**
|
||||
```bash
|
||||
# Disable killswitch (TEMPORARY!)
|
||||
sudo iptables -P INPUT ACCEPT
|
||||
sudo iptables -P OUTPUT ACCEPT
|
||||
sudo iptables -P FORWARD ACCEPT
|
||||
sudo iptables -F
|
||||
|
||||
# Reinstall
|
||||
curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/main/install.sh | bash
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue