Skip to Content
DocsApplicationsUtilitiesVPN (OpenVPN)
OpenVPN

VPN (OpenVPN)

Run an OpenVPN server through QuickBox, generate user-specific client bundles, and download them securely from the dashboard route.

Overview

QuickBox ships OpenVPN as the built-in VPN utility, installing the server, EasyRSA PKI, iptables NAT, and nginx delivery for client bundles in one flow. The qb installer builds server and client certificates, enables the openvpn-server@server service, and seeds per-user .ovpn profiles plus a zipped download endpoint.

OpenVPN here is a packaged VPN server— it does not provide split tunneling or advanced policy routing beyond the defaults in the shipped configs.

Key features

These highlights come directly from the packaged scripts and configs.

⚡ One-command server build

qb creates PKI with EasyRSA, installs OpenVPN, and enables openvpn-server@server with iptables NAT on 10.8.0.0/24.

📦 Per-user client bundle

Generates /etc/openvpn/client/username.ovpn with embedded CA, cert, key, and tls-crypt block, plus a zipped download.

🔑 Secure bundle delivery

nginx location /username/ovpn.zip serves the profile with basic auth backed by /etc/htpasswd.d/htpasswd.username.

🌐 IP forwarding enabled

Ships /etc/sysctl.d/99-ipforward.conf to turn on net.ipv4.ip_forward=1 for VPN routing.

🛡️ Connect/disconnect logging

Client hooks log to /etc/openvpn/server/logs/ via client-connect.sh and client-disconnect.sh.

🔧 Port & firewall wiring

Defaults to UDP 55000 (autogen), opens iptables/SELinux/UFW rules, and SNATs VPN egress to the server IP.

When to use it

Pick OpenVPN when you want a packaged VPN server with qb-managed PKI, firewall rules, and downloadable client bundles.

Symptoms

  • You need remote access to services behind QuickBox over an encrypted tunnel.
  • You want qb to build PKI, server config, and firewall rules automatically.
  • You need per-user client profiles that can be downloaded from the dashboard route.

Resolution

  • Install with qb install vpn -u username to build the server, PKI, and a user bundle in one step.
  • Regenerate or replace a client profile by reinstalling for that user; qb rebuilds username.ovpn and the zip.
  • Download the bundle from webroot/username/ovpn.zip (protected by basic auth) and import it into any OpenVPN client.

Installation

OpenVPN is an admin-installed package. Use qb from an admin shell to build the server, PKI, and per-user bundle.

Install from the QuickBox CLI

Admin-only install

Install from an admin session. Each run provisions the server service, PKI, firewall rules, and a user-specific client bundle protected by nginx basic auth.

qb install vpn -u username

CLI command reference

These commands control install lifecycle and bundle regeneration.

CLI commands and flags

qb install vpn -u username

Builds the OpenVPN server, PKI, iptables/SELinux/UFW rules, and generates username.ovpn plus a zipped bundle.

qb update vpn -u username

Refreshes the package and keeps the existing server settings; use when updating OpenVPN/EasyRSA builds.

qb reinstall vpn -u username

Recreates the client profile and nginx download route for the user using current server settings.

qb remove vpn -u username

Revokes the user cert, removes the client bundle, nginx route, and purges OpenVPN when it is the last instance.

Access and authentication

URL / route

After install, qb writes an nginx location at /username/ovpn.zip pointing to the zipped bundle in the user config directory. Download it from webroot/username/ovpn.zip.

Credentials / profiles

The bundle username-ovpn.zip contains username.ovpn with embedded CA, cert, key, and tls-crypt data. The download endpoint uses basic auth defined in /etc/htpasswd.d/htpasswd.username.

Security notes

  • The server listens on UDP 55000 (auto-generated; templated into server.conf and client files).
  • IP forwarding is enabled via /etc/sysctl.d/99-ipforward.conf; keep it present for routing.
  • NAT and INPUT rules are added with iptables (and firewalld/ufw/SELinux adjustments when present); verify if you maintain custom firewall policies.

Configuration and files

Key paths created by the installer are mapped below.

Important paths
OpenVPN deployment
/etc/openvpn/server/server.conf# Server config with UDP port, push routes, and hook scripts
/etc/openvpn/server/ccd/# Client hook scripts and logs
├── client-connect.sh# Logs client connects to /etc/openvpn/server/logs/
└── client-disconnect.sh# Logs client disconnects to /etc/openvpn/server/logs/
/etc/openvpn/client/username.ovpn# User profile with embedded keys and tls-crypt block
/home/username/.config/OpenVPN/username-ovpn.zip# Downloadable bundle served via nginx route
/etc/nginx/software/username.ovpn.conf# nginx location for /username/ovpn.zip with basic auth
/etc/sysctl.d/99-ipforward.conf# Enables net.ipv4.ip_forward=1 for VPN routing

Common tasks

Routine maintenance and bundle handling through qb and systemd.

Start / stop / restart

sudo systemctl status openvpn-server@server
sudo systemctl restart openvpn-server@server

Updating / reinstalling

qb update vpn -u username
qb reinstall vpn -u username

Typical workflows

  • Install for a user with qb; download username-ovpn.zip from webroot/username/ovpn.zip; import into an OpenVPN client.
  • Rotate a client profile after credential changes by running qb reinstall vpn -u username to rebuild certificates and the zip.
  • If the VPN port changes, reinstall so server.conf and username.ovpn get the new port.
  • After firewall policy changes, verify iptables/SELinux/ufw rules still allow UDP 55000 and the SNAT rule for 10.8.0.0/24.

Best practices

Keep the server, firewall, and bundle delivery aligned with the packaged configuration.

Do

  • Use qb install vpn -u username so PKI, iptables, SELinux/ufw, and nginx routes are configured together.
  • Protect the download route with strong htpasswd credentials and rotate them when rotating client bundles.
  • Verify net.ipv4.ip_forward stays enabled and the SNAT rule persists after firewall changes.
  • Store and share only the zipped bundle; avoid copying raw keys from /etc/openvpn unless you repackage them securely.

Don't

  • Do not hand-edit server.conf or client hooks unless you know OpenVPN directives and will revalidate after changes.
  • Avoid exposing UDP 55000 without checking firewall/NAT placement; keep it limited to intended clients.
  • Do not delete the nginx auth file or username-ovpn.zip before users have pulled updated bundles.

Troubleshooting

Clients cannot connect or time out

Symptom: Connection stalls or fails to reach the server.


Checks: Confirm UDP 55000 is open in iptables/firewalld/ufw; ensure openvpn-server@server is running; reinstall so username.ovpn has the correct public IP/port.

Tunnel up but no traffic

Symptom: VPN connects but cannot reach LAN/Internet.


Checks: Ensure /etc/sysctl.d/99-ipforward.conf is present and net.ipv4.ip_forward is 1; verify the SNAT rule for 10.8.0.0/24 exists; restart after firewall policy changes.

Bundle download denied

Symptom: 401/404 when fetching /username/ovpn.zip.


Checks: Confirm /etc/nginx/software/username.ovpn.conf exists and nginx is loaded; verify /etc/htpasswd.d/htpasswd.username credentials; rerun qb reinstall if the route or zip is missing.

Resources

Resources

OpenVPN documentation

Official guides for server and client configuration.

OpenVPN downloads

Desktop and mobile client installers compatible with the generated .ovpn.

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
phpMyAdminWireGuard VPN