WireGuard VPN

Kernel-fast VPN tunnels with QuickBox CLI + dashboard control

WireGuard® on QuickBox Pro provides a lightweight VPN tunnel for routing server or application traffic through trusted endpoints. The QuickBox integration covers CLI automation, dashboard uploads, automatic MTU tuning, NAT rules, and stored keys for visual status. It includes app-scoped routing for isolating specific application traffic (Emby, Jellyfin, Plex) through WireGuard tunnels using Linux network namespaces. Plan firewall and routing rules accordingly for any additional traffic policies.

Installation

Prerequisites

Install via qb (CLI)

# Server setup with one client profile and NAT rules
qb install wireguard -u username -o server -lp 51820 -noc 1 -dns 1.1.1.1 \
  -cidr 10.5.0.2/16 -cai "0.0.0.0/0,::/0" -ep vpn.example.com \
  -pur "iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" \
  -pdr "iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE"
 
# Client-mode installer (paste config when prompted)
qb install wireguard -u username -o client
 
# Reinstall in place (keeps stash under /etc/v4-dashboard/wg)
qb reinstall wireguard -u username -o server
 
# Remove WireGuard entirely
qb remove wireguard -u username

Install from the dashboard (VPN Control)

1. Open System → VPN Control (admin only).
2. Click Install WireGuard → choose Client (upload .conf) or Server (enter listen port, client count, CIDR, allowed address, endpoint, DNS, PostUp/PostDown).
3. Submit. Uploaded configs are written to /etc/v4-dashboard/wg/, server builds land in /etc/wireguard/ and are synced back to the stash.
4. Use the peer table to toggle Active (starts/stops wg-quick@<name>), view ping/location, and delete peers.

Basic Usage

Activate or swap a profile

# Sync a stored config to /etc/wireguard and start the service
qb manage wireguard check -cn nvpn_us1234
 
# Stop and remove the active client config
qb manage wireguard check --deactivate -cn nvpn_us1234
 
# Remove a stored profile and its service unit
qb manage wireguard remove -cn nvpn_us1234

• Dashboard: toggle the Active checkbox for a peer in VPN Control to start/stop wg-quick@<peer>. Location, ping, and redacted config preview come from /etc/v4-dashboard/wg/<peer>.conf and the cached IP lookup.
• CLI: qb manage wireguard check rewrites /etc/wireguard/<peer>.conf, enables wg-quick@<peer>, and updates user_software.software_alt_port so the dashboard stays in sync.

Add client or server configs (CLI)

# Add a client profile (paste config when prompted)
qb manage wireguard add --client -cn wg-client
 
# Add a server profile with custom CIDR, allowed IPs, and port
qb manage wireguard add --server -lp 51820 -cidr 10.5.0.2/16 \
  -cai "0.0.0.0/0,::/0" -noc 3 -pur "iptables -A FORWARD -i %i -j ACCEPT" \
  -pdr "iptables -D FORWARD -i %i -j ACCEPT"

NordVPN config generator (built-in helper)

# Generate up to 5 NordVPN WireGuard profiles (stores as nvpn_<host>.conf)
nvpn_conf_gen -t "<nordvpn_token>" -c "United States" -L 5 -dns 103.86.96.100
 
# List available countries
nvpn_conf_gen -l
 
# MTU tuning is automatic per endpoint (calls qb manage wireguard calc --mtu internally)

Configuration locations

CLI options

Common workflows

• Install + generate server peers: qb install wireguard -u username -o server -noc 3 ... writes wg0.conf and wg{n}-client.conf into the stash; use VPN Control to download or activate a specific peer.
• Import a provider profile: Upload .conf in VPN Control or qb manage wireguard add --client -cn provider and paste; MTU is injected if missing and permissions are normalized.
• Activate/rotate endpoints: Use peer table toggle or qb manage wireguard check -cn <peer> to bring up a tunnel; use --deactivate to tear down before switching regions.
• Generate NordVPN sets: nvpn_conf_gen -t <token> -c "United States" -L 5 outputs nvpn_<hostname>.conf files ready for activation.
• Reinstall safely: qb reinstall wireguard -u username -o server refreshes binaries and configs while keeping the stash in /etc/v4-dashboard/wg.

App-scoped routing

App-scoped routing lets you send only a specific application’s network traffic through a WireGuard tunnel while all other server traffic uses the default route. Each routed app runs inside its own Linux network namespace with a dedicated WireGuard interface, so there is complete traffic isolation with no interference between apps or the host.

Supported applications

How to enable from the dashboard

1. Navigate to System > VPN Control (admin only).
2. Upload at least one WireGuard client .conf file if you have not already.
3. Scroll to the App-Scoped Routing card.
4. Select the application you want to route (only installed apps with running services appear).
5. If the app has multiple service instances (e.g., Emby installed for several users), select the instance.
6. Choose a WireGuard peer config from the dropdown.
7. Click Enable Routing.

The dashboard shows a live health indicator once routing is active, confirming that the namespace, WireGuard interface, and routing rules are all in place.

Kill switch protection

The kill switch is an optional safety net that fully stops the routed application’s service if the VPN tunnel degrades. This prevents any traffic from leaking outside the VPN.

• Trigger threshold: Configurable between 60 and 3,600 seconds (default 600 seconds / 10 minutes). The kill switch fires when the WireGuard handshake age exceeds this threshold.
• Auto-recovery: When enabled, the system attempts to restore VPN routing automatically after a kill switch event using exponential backoff (2 minutes, 4 minutes, 8 minutes, 16 minutes, 30 minutes) up to 5 attempts.
• Manual re-enable: If auto-recovery is disabled or all 5 attempts are exhausted, an admin must manually re-enable routing from VPN Control.

Configure the kill switch from the Kill Switch Protection panel that appears after routing is enabled for an app.

How it works (overview)

1. A dedicated Linux network namespace is created for the app (e.g., qb_emby, qb_plex).
2. A WireGuard interface is configured inside the namespace using the selected peer config.
3. A veth pair bridges the namespace to the host so the reverse proxy can still reach the app.
4. The app’s systemd service is restarted inside the namespace.
5. All traffic originating from the app exits through the VPN tunnel. Incoming requests from the dashboard’s reverse proxy reach the app through the veth bridge.
6. When routing is disabled, the namespace is torn down and the service restarts on the normal host network.

A background health monitor polls every 30 seconds to verify the namespace, WireGuard interface, and routing rules are intact. If the kill switch is enabled and the tunnel handshake goes stale, the monitor takes protective action.

Best practices

Troubleshooting

FAQ

Additional resources