mvpg/docs/PROVIDERS.md

# 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
```