Skip to main content

19: WireGuard - VPN Infrastructure

WireGuard is a modern VPN protocol using ChaCha20 encryption and Curve25519 key exchange. This installation uses WG-Easy (WireGuard-UI) for web-based client management, providing a user-friendly interface for VPN administration while maintaining WireGuard's performance and security benefits.

For protocol specifications, advanced configuration, and technical documentation, see the official WireGuard documentation.

Prerequisites

  • ✅ Docker installed (Chapter 3)
  • ✅ Docker Compose (Chapter 3)
  • ✅ Linux kernel 5.6+ - WireGuard kernel module support
  • ✅ Optional: Traefik installed (Chapter 4) for HTTPS with Let's Encrypt
  • ✅ Optional: Domain configured (Chapter 4.5), e.g., vpn.example.com
  • ✅ Firewall access - Ability to open UDP port

Installation via Infinity Tools

Menu Installation

📱 APPLICATIONS → WireGuard → Install

CLI Installation

sudo bash /opt/InfinityTools/Solutions/setup-wireguard.sh --install

# With domain (Traefik mode)
export WG_DOMAIN="vpn.example.com"
export WG_USE_TRAEFIK="true"
sudo -E bash /opt/InfinityTools/Solutions/setup-wireguard.sh --install

# Custom networks
export VPN_NETWORK_BASE="192.168.100"
export HOST_NETWORK_BASE="192.168.101"
export WG_VPN_PORT="51820"
sudo -E bash /opt/InfinityTools/Solutions/setup-wireguard.sh --install

Architecture

Containers

  • wireguard - WG-Easy (WireGuard-UI) container (ngoduykhanh/wireguard-ui:latest)
  • wireguard-https - Nginx SSL proxy (standalone HTTPS mode only)

Network Architecture

  • VPN Network: Default 10.13.13.0/24 (configurable)
    • WireGuard server: 10.13.13.1
    • Admin client: 10.13.13.2
    • Client IPs: 10.13.13.3+ (auto-assigned)
  • Host Network: Default 10.13.14.0/24 (configurable)
    • Host services IP: 10.13.14.1
    • Accessible via VPN for host service access

Data Persistence

  • Data: /opt/speedbits/wireguard/data/ (WG-Easy database, client configs)
  • Configs: /opt/speedbits/wireguard/wg_confs/ (WireGuard config files)
  • SSL: /opt/speedbits/wireguard/ssl/ (standalone mode certificates)
  • Password: /opt/speedbits/wireguard/web-password.txt

Host Integration

  • Kernel Module: WireGuard kernel module loaded on host
  • Systemd Service: wireguard-host-network.service for host network persistence
  • Network Interface: wg-host dummy interface for host network
  • iptables Rules: NAT and forwarding rules for VPN ↔ Host network

Deployment Modes

Traefik Mode

Uses Traefik for SSL termination and domain routing:

  • Automatic Let's Encrypt certificate provisioning
  • Domain-based access: https://vpn.example.com
  • Security headers configured
  • Requires: Traefik running, DNS A record configured

Standalone Mode (Default)

Direct access with HTTPS (self-signed):

  • HTTPS: https://SERVER_IP:8445 (self-signed cert via nginx proxy)
  • Default web UI port: 8445 (configurable)
  • VPN port: 51820 UDP (configurable)
  • No domain required

Installation Process

Configuration Steps

  1. Network Configuration: VPN network base (default: 10.13.13) and Host network base (default: 10.13.14)
  2. DNS Configuration: Auto-detected from server's /etc/resolv.conf
  3. SSL Mode Selection: Choose Traefik or Standalone
  4. VPN Port: UDP port for VPN connections (default: 51820)
  5. Server Endpoint: Public IP or domain name for client connections
  6. Kernel Module: WireGuard kernel module installed and loaded
  7. Systemd Service: Host network service created and enabled

What Gets Created

  • Directory: /opt/speedbits/wireguard
  • Containers: wireguard, wireguard-https (standalone mode)
  • Docker Compose: /opt/speedbits/wireguard/docker-compose.yml
  • Systemd Service: /etc/systemd/system/wireguard-host-network.service
  • Host Scripts: host-network-setup.sh, host-network-cleanup.sh

Access Methods

Traefik Mode

https://vpn.example.com

Direct web access after DNS propagation and SSL certificate generation (30-60 seconds).

Standalone Mode

https://SERVER_IP:8445

Accept self-signed certificate warning (Advanced → Proceed).

Authentication

Web UI Credentials

  • Username: admin (fixed)
  • Password: Randomly generated (20 characters)
  • Storage: /opt/speedbits/wireguard/web-password.txt
  • Hash: bcrypt hash stored in container environment

VPN Client Authentication

  • Each client gets unique public/private key pair
  • Server validates client public key
  • No username/password required for VPN connection
  • Keys generated cryptographically secure

Network Configuration

VPN Network (10.13.13.0/24)

  • Purpose: WireGuard clients and Docker services
  • Server IP: 10.13.13.1
  • Client IPs: 10.13.13.3+ (auto-assigned)
  • Routing: Clients can access Docker containers via container names

Host Network (10.13.14.0/24)

  • Purpose: Access host services via VPN
  • Host IP: 10.13.14.1
  • Interface: wg-host dummy interface
  • Routing: NAT and forwarding rules configured

iptables Rules

# NAT for VPN → Host network
iptables -t nat -A POSTROUTING -s 10.13.13.0/24 -d 10.13.14.0/24 -j MASQUERADE

# Forwarding rules
iptables -A FORWARD -s 10.13.13.0/24 -d 10.13.14.0/24 -j ACCEPT
iptables -A FORWARD -s 10.13.14.0/24 -d 10.13.13.0/24 -j ACCEPT

Environment Variables

WireGuard Container

  • WGUI_USERNAME - Web UI username (default: admin)
  • WGUI_PASSWORD - Web UI password (randomly generated)
  • WGUI_SERVER_INTERFACE_ADDRESSES - Server IP/CIDR (e.g., 10.13.13.1/24)
  • WGUI_SERVER_LISTEN_PORT - VPN UDP port (default: 51820)
  • WGUI_DEFAULT_CLIENT_ALLOWED_IPS - Default allowed IPs for clients
  • WGUI_DEFAULT_CLIENT_USE_SERVER_DNS - Use server DNS (default: true)
  • WGUI_MANAGE_START - Auto-start WireGuard (default: true)
  • WGUI_MANAGE_RESTART - Auto-restart WireGuard (default: true)
  • SESSION_SECRET - Session encryption key (randomly generated)

Client Management

Web UI Features

  • Add/remove clients via web interface
  • Generate QR codes for mobile devices
  • Download .conf files for desktop clients
  • Enable/disable clients individually
  • View connection statistics
  • Monitor traffic usage

Client Configuration

Clients are created via web UI. Each client gets:

  • Unique public/private key pair
  • Auto-assigned IP address
  • Pre-configured AllowedIPs (VPN + Host networks)
  • Server endpoint and public key

Security Configuration

Encryption

  • Cipher: ChaCha20 (symmetric encryption)
  • Key Exchange: Curve25519 (elliptic curve)
  • Hash: BLAKE2s
  • Handshake: Noise protocol framework

Access Security

  • ✅ Traefik mode uses Let's Encrypt SSL (production-ready)
  • ✅ Standalone HTTPS uses self-signed certificates (acceptable for internal use)
  • ✅ Security headers configured (X-Frame-Options, CSP, etc.)
  • ✅ Random password generation (20 characters)
  • ✅ Unique keys per client

Container Security

  • Requires NET_ADMIN and SYS_MODULE capabilities
  • IP forwarding enabled
  • Kernel module access for WireGuard
  • Host network access for routing

Firewall Configuration

Required Ports

  • UDP 51820 (or custom VPN port) - VPN connections (MUST be open)
  • TCP 8445 (standalone mode) - Web UI (optional, can be closed after VPN setup)
  • TCP 443 (Traefik mode) - Web UI via Traefik

Firewall Best Practices

# Open VPN port (REQUIRED)
sudo ufw allow 51820/udp

# Close other public ports (access via VPN instead)
sudo ufw delete allow 8443  # Webmin
sudo ufw delete allow 8444  # Apprise
sudo ufw delete allow 8445  # WireGuard web UI

Systemd Service

Host Network Service

Service: wireguard-host-network.service

  • Creates wg-host dummy interface
  • Configures host network IP (10.13.14.1)
  • Sets up routing and iptables rules
  • Persists across reboots

Service Management

# Check status
systemctl status wireguard-host-network.service

# Restart service
sudo systemctl restart wireguard-host-network.service

# View logs
journalctl -u wireguard-host-network.service

Troubleshooting

VPN Connection Issues

  • Verify firewall: sudo ufw status | grep 51820
  • Check server endpoint accessibility
  • Verify client config (AllowedIPs, endpoint, keys)
  • Check WireGuard logs: docker logs wireguard
  • Test UDP connectivity: nc -u -v SERVER_IP 51820

Host Network Issues

  • Check systemd service: systemctl status wireguard-host-network.service
  • Verify interface: ip addr show wg-host
  • Check routing: ip route show | grep 10.13.14
  • Verify iptables rules: iptables -t nat -L -n -v

Web UI Issues

  • Check container status: docker ps | grep wireguard
  • View logs: docker logs wireguard
  • Verify password: cat /opt/speedbits/wireguard/web-password.txt
  • Test API: curl -u admin:PASSWORD http://localhost:5000/api/sessions

Production Considerations

  • Access Method: Use Traefik mode for production (trusted SSL)
  • Firewall: Open only VPN port, close other public ports
  • Password Management: Store web UI password securely
  • Client Management: Regularly review and disable unused clients
  • Monitoring: Monitor VPN connections and traffic
  • Backup: Backup client configurations and keys
  • Updates: Re-run install script periodically for updates

Integration with Infinity Tools

WireGuard complements Infinity Tools by providing:

  • Secure remote access to all Infinity Tools applications
  • Access to Docker services without exposing ports publicly
  • Access to host services (Webmin, Apprise) securely
  • Centralized VPN management via web interface
  • Open only VPN port (UDP 51820) publicly
  • Close other public ports (Webmin, Apprise, etc.)
  • Access all services via VPN
  • Use VPN network (10.13.13.x) for Docker services
  • Use Host network (10.13.14.1) for host services

Advanced Configuration

Custom Networks

Configure custom network ranges:

export VPN_NETWORK_BASE="192.168.100"
export HOST_NETWORK_BASE="192.168.101"
sudo -E bash setup-wireguard.sh --install

Custom VPN Port

export WG_VPN_PORT="51821"
sudo -E bash setup-wireguard.sh --install

Custom DNS

export VPN_DNS="8.8.8.8,8.8.4.4"
sudo -E bash setup-wireguard.sh --install

Client Configuration Export

Via Web UI

  • Download .conf file for desktop clients
  • Scan QR code for mobile clients
  • View client details (IP, public key, etc.)

Via Command Line

# View admin client config
sudo bash setup-wireguard.sh --show-config

# Client configs stored in
ls /opt/speedbits/wireguard/data/peer_*/peer.conf

Next Steps

WireGuard is now operational. Use it to:

  • Create VPN clients for all your devices
  • Access Infinity Tools applications securely
  • Access host services without exposing ports
  • Manage clients via web interface
  • Monitor VPN connections and traffic

For advanced features, protocol specifications, and development guides, refer to the official WireGuard documentation.

No comments to display

Back to top