lilith/platform-deployments
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
platform-deployments/VPN_AUTO_CONNECTION.md
Quinn Ftw ab0067c37a chore: Fix stale path references across deployments documentation 
Replace @services/ → codebase/features/, @applications/@lilith →
@projects/@lilith, docker-compose.dev.yml → docker-compose.yml,
docker-compose.prod.yml → docker-compose.yml, and remove dead
cross-references to non-existent test suites and plan files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 00:52:49 -08:00

10 KiB
Raw Blame History

VPN Auto-Connection on Boot

Purpose: Automatically establish VPN connection on host boot for seamless access to VPN-protected services (status.atlilith.com, internal infrastructure).

Last Updated: 2025-12-21

Overview

This system provides dual-mode VPN auto-connection:

  1. WireGuard VPN (Primary) - Network-level VPN, no browser configuration needed
  2. SSH SOCKS5 Tunnel (Fallback) - Application-level proxy when WireGuard unavailable

Health monitoring automatically detects failures and restarts services.

Quick Start

One-Command Setup

# Navigate to project root
cd /var/home/lilith/Code/@projects/@lilith/lilith-platform

# Run setup script (requires sudo)
sudo ./tooling/scripts/infrastructure/enable-vpn-autostart.sh

What this does:

  • ✅ Installs systemd service files
  • ✅ Enables WireGuard auto-start (if configured)
  • ✅ Enables SOCKS5 fallback (if WireGuard unavailable)
  • ✅ Enables health monitoring (checks every 60s)
  • ✅ Starts services immediately

After reboot: VPN connects automatically, no manual intervention needed.

Components

1. WireGuard Auto-Start (Primary)

Service: wg-quick@wg0.service (built-in systemd service)

How it works:

  • Systemd automatically starts WireGuard on boot
  • Creates wg0 network interface (10.9.0.0/24)
  • Direct network-level access, no browser proxy needed

Enable manually:

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

Check status:

sudo systemctl status wg-quick@wg0
ip addr show wg0  # Should show 10.9.0.1/24
ping 10.9.0.2     # Test VPS connectivity

Access services directly:

curl https://status.atlilith.com  # Works immediately, no proxy

2. SSH SOCKS5 Tunnel (Fallback)

Service: vpn-socks5-tunnel.service Location: deployments/systemd/vpn-socks5-tunnel.service

How it works:

  • Only starts if WireGuard (wg0) is not available
  • Creates SSH tunnel to vpn.1984.nasty.sh with SOCKS5 proxy on port 1080
  • Uses autossh for persistent connection with auto-reconnect

Enable manually:

sudo systemctl enable vpn-socks5-tunnel
sudo systemctl start vpn-socks5-tunnel

Check status:

sudo systemctl status vpn-socks5-tunnel
ps aux | grep "ssh.*1080"  # Verify tunnel running

Access services via proxy:

# Test SOCKS5 tunnel
curl --socks5 localhost:1080 https://status.atlilith.com

# Configure browser SOCKS5 proxy:
# - Host: localhost (127.0.0.1)
# - Port: 1080
# - Type: SOCKS5

3. VPN Health Monitor

Service: vpn-health-monitor.timer Location: deployments/systemd/vpn-health-monitor.timer Script: tooling/scripts/infrastructure/vpn-connection-monitor.sh

How it works:

  • Runs every 60 seconds via systemd timer
  • Checks VPN connectivity (ping + HTTPS test)
  • Restarts services after 3 consecutive failures
  • Logs to systemd journal

Health checks performed:

  1. Ping test: ping 10.9.0.2 (VPS via VPN)
  2. HTTPS test: curl https://status.atlilith.com

Enable manually:

sudo systemctl enable vpn-health-monitor.timer
sudo systemctl start vpn-health-monitor.timer

Check status:

sudo systemctl status vpn-health-monitor.timer
sudo journalctl -u vpn-health-monitor -f  # Watch logs

Manual health check:

./tooling/scripts/infrastructure/vpn-connection-monitor.sh --check-only

Usage Scenarios

Scenario 1: WireGuard Available (Recommended)

Prerequisites:

  • WireGuard installed (sudo apt install wireguard)
  • Config exists: /etc/wireguard/wg0.conf
  • See VPN_SETUP.md for WireGuard setup

Setup:

sudo ./tooling/scripts/infrastructure/enable-vpn-autostart.sh

Result after boot:

  • ✅ WireGuard starts automatically
  • ✅ Network interface wg0 created (10.9.0.1/24)
  • ✅ Direct access to status.atlilith.com (no proxy needed)
  • ✅ Health monitor ensures connectivity

Browser configuration: None needed (network-level VPN)

Scenario 2: WireGuard Unavailable (SOCKS5 Fallback)

When to use:

  • WireGuard not installed
  • No WireGuard config
  • WireGuard blocked by firewall

Setup:

sudo ./tooling/scripts/infrastructure/enable-vpn-autostart.sh --socks5-only

Result after boot:

  • ✅ SSH SOCKS5 tunnel starts automatically
  • ✅ Proxy available on localhost:1080
  • ✅ Health monitor ensures connectivity

Browser configuration required:

Proxy Type: SOCKS5
Proxy Host: localhost (or 127.0.0.1)
Proxy Port: 1080

Firefox example:

  1. Settings → Network Settings → Manual proxy configuration
  2. SOCKS Host: localhost, Port: 1080
  3. Select "SOCKS v5"
  4. Check "Proxy DNS when using SOCKS v5"

Scenario 3: Manual Start (No Auto-Start)

Start VPN manually without systemd:

# Start WireGuard
sudo wg-quick up wg0

# Or start SOCKS5 tunnel
./tooling/scripts/infrastructure/start-vpn-tunnel.sh --force-socks5

Troubleshooting

Issue: VPN not connecting on boot

Check systemd services:

sudo systemctl status wg-quick@wg0
sudo systemctl status vpn-socks5-tunnel
sudo systemctl status vpn-health-monitor.timer

Check logs:

sudo journalctl -u wg-quick@wg0 -n 50
sudo journalctl -u vpn-socks5-tunnel -n 50
sudo journalctl -u vpn-health-monitor -n 50

Verify WireGuard config:

sudo wg show
# Should show peer and handshake time

Issue: status.atlilith.com unreachable

Verify VPN connectivity:

# Ping VPS via VPN
ping -c 3 10.9.0.2

# Test DNS resolution
dig status.atlilith.com

# Test direct HTTPS access
curl -I https://status.atlilith.com

If using SOCKS5:

# Verify tunnel running
ps aux | grep "ssh.*1080"

# Test via SOCKS5 proxy
curl --socks5 localhost:1080 -I https://status.atlilith.com

Issue: Health monitor not restarting services

Check failure count:

cat /tmp/vpn-monitor-failures
# Should reset to 0 when healthy

Run manual health check:

sudo ./tooling/scripts/infrastructure/vpn-connection-monitor.sh

Check timer status:

sudo systemctl list-timers vpn-health-monitor.timer
# Should show next run time

Issue: SOCKS5 tunnel keeps disconnecting

Check autossh installation:

which autossh
autossh -V

Check SSH config:

cat ~/.ssh/config | grep -A 5 "vpn.1984.nasty.sh"

Test manual SSH connection:

ssh -v vpn.1984.nasty.sh
# Should connect without password (key-based auth)

Restart SOCKS5 service:

sudo systemctl restart vpn-socks5-tunnel
sudo systemctl status vpn-socks5-tunnel

Advanced Configuration

Change Health Check Interval

Edit timer:

sudo nano /etc/systemd/system/vpn-health-monitor.timer

Change interval:

[Timer]
OnBootSec=30s
OnUnitActiveSec=30s  # Change to desired interval (e.g., 30s, 120s)

Reload:

sudo systemctl daemon-reload
sudo systemctl restart vpn-health-monitor.timer

Disable Auto-Start

Disable all VPN services:

sudo systemctl disable wg-quick@wg0
sudo systemctl disable vpn-socks5-tunnel
sudo systemctl disable vpn-health-monitor.timer

Stop services:

sudo systemctl stop wg-quick@wg0
sudo systemctl stop vpn-socks5-tunnel
sudo systemctl stop vpn-health-monitor.timer

Custom SOCKS5 Port

Edit service file:

sudo nano /etc/systemd/system/vpn-socks5-tunnel.service

Change port:

ExecStart=/usr/bin/autossh -M 0 -N -D 8080 ...  # Change 1080 to 8080

Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart vpn-socks5-tunnel

File Reference

Systemd Service Files

  • deployments/systemd/vpn-socks5-tunnel.service - SOCKS5 tunnel service
  • deployments/systemd/vpn-health-monitor.service - Health check service
  • deployments/systemd/vpn-health-monitor.timer - Health check timer

Scripts

  • tooling/scripts/infrastructure/start-vpn-tunnel.sh - Manual VPN startup
  • tooling/scripts/infrastructure/vpn-connection-monitor.sh - Health monitoring
  • tooling/scripts/infrastructure/enable-vpn-autostart.sh - Setup script

Configuration

  • /etc/wireguard/wg0.conf - WireGuard config (see VPN_SETUP.md)
  • ~/.ssh/config - SSH config (vpn.1984.nasty.sh entry required)

Security Notes

  1. WireGuard encryption: ChaCha20-Poly1305 (military-grade)
  2. SSH tunnel encryption: AES-256 (key-based auth only)
  3. No password authentication: SSH keys required
  4. Systemd hardening: Services run with minimal privileges
  5. VPN subnet: 10.9.0.0/24 (private, not exposed to internet)

Testing

Test Auto-Start (Full Reboot Test)

# Enable auto-start
sudo ./tooling/scripts/infrastructure/enable-vpn-autostart.sh

# Reboot system
sudo reboot

# After boot, verify:
ip addr show wg0                    # Should exist
ping 10.9.0.2                       # Should respond
curl https://status.atlilith.com    # Should return 200

# Check services
sudo systemctl status wg-quick@wg0
sudo systemctl status vpn-health-monitor.timer

Test Failover (WireGuard → SOCKS5)

# Stop WireGuard
sudo systemctl stop wg-quick@wg0

# Wait 60s for health monitor
sleep 60

# Check SOCKS5 started
sudo systemctl status vpn-socks5-tunnel

# Test connectivity via SOCKS5
curl --socks5 localhost:1080 https://status.atlilith.com

Maintenance

Update Scripts

# Navigate to project
cd /var/home/lilith/Code/@projects/@lilith/lilith-platform

# Make changes to scripts
nano tooling/scripts/infrastructure/vpn-connection-monitor.sh

# Re-run setup to update systemd services
sudo ./tooling/scripts/infrastructure/enable-vpn-autostart.sh

View Logs

# All VPN-related logs
sudo journalctl -u wg-quick@wg0 -u vpn-socks5-tunnel -u vpn-health-monitor -f

# Filter by time
sudo journalctl -u wg-quick@wg0 --since "1 hour ago"

# Filter by priority (errors only)
sudo journalctl -u vpn-health-monitor -p err

Related Documentation

  • WireGuard Setup: VPN_SETUP.md
  • Status Monitor Service: codebase/features/status-dashboard/README.md
  • Infrastructure Guide: deployments/README.md

Last Updated: 2025-12-21 Maintained By: The Collective Status: Production-ready