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 does not ship a policy-based firewall or per-app split tunneling—plan firewall and routing rules accordingly.

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 /srv/quickbox/db/wireguard)
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 /srv/quickbox/db/wireguard/, 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 /srv/quickbox/db/wireguard/<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 /srv/quickbox/db/wireguard.

Best practices

Troubleshooting

Additional resources