streamflow/docs/VPN_TEST_GUIDE.md

VPN Fix - Quick Testing Guide

1. Rebuild the Container

cd /home/iulian/projects/tv
docker-compose down
docker-compose build --no-cache
docker-compose up -d

2. Test VPN Connection

From Web UI:

1. Navigate to Settings → VPN
2. Enter your ProtonVPN credentials:
   • Username: your-protonvpn-username
   • Password: your-protonvpn-password
3. Click "Save Settings"
4. Select a country (e.g., United States)
5. Click "Connect to [Country]"
6. Wait for "VPN Connected" message
7. Click "Check IP" button
8. Verify the results:
   • ✓ Public IP is different from your real IP
   • ✓ Location shows VPN country
   • ✓ ISP contains "Proton" or VPN-related text
   • ✓ DNS servers show 10.2.0.1, 10.2.0.2
   • ✓ VPN Interface badge shows "Active" (green)

From Command Line (Inside Container):

# Enter the container
docker exec -it streamflow bash

# Run the test script
./scripts/test-vpn.sh

# Or manual tests:
# Check VPN interface
ip addr show tun0

# Check your public IP
curl https://api.ipify.org

# Check DNS
cat /etc/resolv.conf

# Check routing
ip route | grep default

3. API Testing

Check IP Address

# Get your auth token first from browser DevTools (Application → Local Storage)
TOKEN="your-jwt-token"

# Check current IP
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:12345/api/vpn/check-ip | jq

Expected output:

{
  "publicIp": "X.X.X.X",
  "ipInfo": {
    "ip": "X.X.X.X",
    "city": "...",
    "country": "US",
    "org": "AS... ProtonVPN..."
  },
  "dnsServers": ["10.2.0.1", "10.2.0.2"],
  "vpnInterfaceActive": true
}

Run Full Diagnostics

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:12345/api/vpn/diagnostics | jq

4. Expected Behavior

BEFORE FIX (Broken):

• ❌ Real IP visible after VPN connect
• ❌ DNS servers: 8.8.8.8, 1.1.1.1 (public DNS)
• ❌ ISP shows your real ISP
• ❌ Location shows your real location

AFTER FIX (Working):

• ✅ VPN IP visible (different from real IP)
• ✅ DNS servers: 10.2.0.1, 10.2.0.2 (ProtonVPN DNS)
• ✅ ISP shows ProtonVPN or similar
• ✅ Location shows VPN country
• ✅ VPN interface (tun0) active
• ✅ Default route goes through tun0

5. Troubleshooting

VPN won't connect:

# Check backend logs
docker logs streamflow --tail 100

# Look for:
# - "[VPN] Successfully connected!"
# - "Initialization Sequence Completed"

Connected but real IP still shows:

# Inside container
docker exec -it streamflow bash

# Check if tun0 exists
ip addr show tun0

# Check routing
ip route

# Should show: default via X.X.X.X dev tun0

DNS Leak:

# Check DNS servers
docker exec -it streamflow cat /etc/resolv.conf

# Should show:
# nameserver 10.2.0.1
# nameserver 10.2.0.2

Can't access container after VPN:

• Ensure ports are still mapped in docker-compose.yml
• Check if firewall is blocking incoming connections
• Try accessing from localhost vs external IP

6. Common Issues

Issue	Solution
"VPN not configured" error	Save credentials first before connecting
Connection timeout	Try different country/server
Real IP still visible	Check logs, verify tun0 exists, restart VPN
DNS leak detected	Rebuild container to fix DNS script
No internet when VPN connected	Check OpenVPN logs, try different server
"NET_ADMIN capability" error	Add capabilities to docker-compose.yml

7. Verify Changes Applied

Check Dockerfile has updated DNS script:

grep -A 5 "Update DNS when VPN" Dockerfile

Should include the for loop to parse foreign_option_*

Check vpn.js has kill switch:

grep -A 5 "setupFirewall" backend/routes/vpn.js

Should include iptables rules

Check diagnostics utility exists:

ls -l backend/utils/vpnDiagnostics.js

Should exist and be readable

8. Before/After Comparison

Test the same command before and after connecting to VPN:

# Before VPN
curl https://api.ipify.org
# Output: Your real IP (e.g., 93.114.x.x)

# Connect VPN via UI

# After VPN
curl https://api.ipify.org
# Output: VPN IP (e.g., 185.159.x.x)

# Check location
curl https://ipinfo.io/$(curl -s https://api.ipify.org)/json | jq '.country'
# Should show VPN country code

9. Files Changed

Summary of modified files:

• ✓ Dockerfile - Fixed DNS script
• ✓ backend/routes/vpn.js - Added kill switch, verification, diagnostics
• ✓ backend/utils/vpnDiagnostics.js - NEW diagnostic utility
• ✓ frontend/src/components/VPNSettings.jsx - Added Check IP button
• ✓ scripts/test-vpn.sh - NEW test script
• ✓ docs/VPN_TROUBLESHOOTING.md - NEW troubleshooting guide
• ✓ VPN_FIX_SUMMARY.md - NEW summary document

10. Success Criteria

VPN is working correctly when:

• VPN connects without errors
• Public IP is VPN IP (not real IP)
• Location matches VPN country
• DNS servers are ProtonVPN DNS
• VPN interface (tun0) is active
• All traffic routes through tun0
• Streaming works through VPN
• No DNS leaks
• Kill switch active (traffic blocked if VPN drops)

---

Need help? See docs/VPN_TROUBLESHOOTING.md for detailed troubleshooting steps.