Skip to Content
DocsApplicationsUtilitiesVPN (OpenVPN)
OpenVPN

VPN (OpenVPN)

Run an OpenVPN server through QuickBox, pick the port, protocol, subnet, and DNS at install time, generate user-specific client bundles, and download them securely from the dashboard route.

Overview

QuickBox ships OpenVPN as the built-in SSL/TLS VPN utility, installing the server, EasyRSA PKI, iptables NAT, and nginx delivery for client bundles in one flow. The installer compiles OpenVPN, builds the server and client certificates, enables the openvpn-server@server service, and seeds a per-user .ovpn profile plus a zipped download endpoint. Administrators can run the install from the dashboard’s Package Management page (a modal sets the port, protocol, subnet, and DNS) or from the qb CLI — both paths drive the same installer.

The first user you install for provisions the server itself — that first run is where the listen port, transport protocol, client subnet, and pushed DNS are chosen. Every later user inherits the server settings and only gets their own client profile generated. Accepting the defaults (UDP 55000, subnet 10.8.0.0/24, DNS 1.1.1.1,1.0.0.1) — whether through the dashboard modal or a plain qb install vpn -u username — keeps existing flows unchanged.

OpenVPN works in two directions on QuickBox. As a server, it accepts inbound clients connecting into your box (the per-user .ovpn bundles above). As a client backend for app-scoped routing, it dials out through a remote VPN — you upload a provider’s .ovpn (Mullvad, PIA, NordVPN, etc.) in the dashboard and route a single application’s traffic through it. Both surfaces are managed from the VPN Control page in the dashboard, which gained a full OpenVPN management surface alongside WireGuard.

Key features

These highlights come directly from the packaged scripts and configs.

One-command server build

qb compiles OpenVPN, creates the PKI with EasyRSA, enables openvpn-server@server, and SNATs the client subnet (default 10.8.0.0/24) to the server IP.

Install-time selection

Choose the listen port (-lp), protocol (-proto, udp/tcp), client subnet (-sub), and pushed DNS (-dns) on the first install. Later users inherit the server settings.

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

An nginx location at /username/ovpn.zip serves the profile behind 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.

Tagged firewall wiring

Opens iptables/firewalld/UFW/SELinux rules for the chosen port and protocol; every rule carries a qbx:vpn tag so the dashboard firewall view classifies it and remove reverses it cleanly.

Dashboard management

VPN Control surfaces the OpenVPN server status, per-user profile downloads, and client-tunnel management (upload, activate, deactivate, delete) for administrators.

App-scoped routing backend

Route a single app (Emby, Jellyfin, Plex, qBittorrent, Dispatcharr) out through an uploaded provider .ovpn using a per-app network namespace — the OpenVPN counterpart to WireGuard routing.

When to use it

Pick OpenVPN when you want a packaged SSL/TLS VPN server with qb-managed PKI, firewall rules, and downloadable client bundles, with control over the port, protocol, subnet, and DNS at install time.

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 to choose a non-default port, TCP transport, or a custom client subnet.
  • 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 with the defaults.
  • Set -lp, -proto, -sub, and -dns on the first install to choose the server port, protocol, subnet, and pushed DNS.
  • 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. Administrators can install it from the dashboard’s Package Management page or with qb from an admin shell — either path builds the server, PKI, and per-user bundle.

Install from the QuickBox CLI

Admin-only install

Install from an admin session. The first install on the box provisions the server service, PKI, and firewall rules; every install also creates a user-specific client bundle protected by nginx basic auth.

# Defaults: UDP 55000, subnet 10.8.0.0/24, DNS 1.1.1.1,1.0.0.1
qb install vpn -u username
# Choose the server port, protocol, subnet, and pushed DNS on the FIRST install
qb install vpn -u username -lp '1194' -proto 'tcp' -sub '10.9.0.0/24' -dns '9.9.9.9,8.8.8.8'
Server settings are set by the first user

The server-level options (-lp, -proto, -sub, -dns) are applied when the first user’s profile sets up the OpenVPN server. Subsequent users inherit the server’s existing port, protocol, subnet, and DNS — passing the flags again for a later user has no effect on the running server.

Install from the Dashboard

Administrators can also provision the OpenVPN server straight from the dashboard. Open Package Management, find OpenVPN, and click Install — a configuration modal appears with the same server-level options the CLI exposes:

FieldDefaultCLI flag
Listen Port
55000
-lp
Protocol
UDP (UDP / TCP)
-proto
Client Subnet (CIDR)
10.8.0.0/24
-sub
Pushed DNS
1.1.1.1,1.0.0.1
-dns

Submitting the modal runs qb install vpn -u <user> -lp <port> -proto <protocol> -sub <subnet> -dns <dns> on your behalf, building the server, PKI, firewall rules, and the first user’s client bundle — identical to running the command yourself. Like the CLI path, these server-level options are fixed by the first install and inherited by every later user.

Once the server is installed, the dashboard’s VPN Control page (under System > VPN Control) gives administrators a full OpenVPN surface: server status, per-user profile downloads, and client-tunnel management — uploading provider .ovpn files and activating, deactivating, or deleting them for app-scoped routing. See Managing OpenVPN from the dashboard below.

CLI command reference

These commands control the install lifecycle and bundle regeneration.

CLI commands and flags

-u, --username

User the per-user .ovpn profile is generated for (required).

-lp, --listen-port

Server listen port, applied on the first install. Default: 55000.

-proto, --protocol

Transport protocol, udp or tcp, applied on the first install. Default: udp.

-sub, --subnet

VPN client subnet in CIDR form, applied on the first install. Default: 10.8.0.0/24.

-dns, --dns-server

Pushed DNS server(s), comma-separated, applied on the first install. Default: 1.1.1.1,1.0.0.1.

qb install vpn -u username

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

qb reinstall vpn -u username

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

qb remove vpn -u username

Revokes the user cert, removes the client bundle and nginx route, and purges OpenVPN and its firewall rules 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 the chosen port and protocol (default UDP 55000), templated into server.conf and the client profile.
  • Profiles ship modern GCM-only ciphers (AES-256-GCM/AES-128-GCM data ciphers with a tls-crypt control-channel wrapper, a TLS 1.2 floor, and SHA256 control-channel auth) and disable compression to avoid VORACLE-class attacks. Legacy CBC ciphers are not offered, so there is no downgrade path.
  • Revoked certificates are enforced through the server’s certificate revocation list (CRL). When you ban or delete a user, their OpenVPN certificate is revoked and their existing .ovpn stops connecting immediately — it does not wait for a server restart.
  • 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) and tagged qbx:vpn; verify placement if you maintain custom firewall policies.

Configuration and files

Key paths created by the installer are mapped below.

Important paths
/
opt/OpenVPN/# Source build/working directory for the compiled OpenVPN binaries
etc/openvpn/# OpenVPN data root (PKI, server, client, easy-rsa)
├── server/server.conf# Server config with the chosen port/protocol, subnet, push routes, and hook scripts
├── server/ccd/# Client-config-dir plus connect/disconnect hook scripts
│ ├── client-connect.sh# Logs client connects under /etc/openvpn/server/logs/
│ └── client-disconnect.sh# Logs client disconnects under /etc/openvpn/server/logs/
├── pki/# EasyRSA PKI: CA, server/client certs, keys, CRL, DH params
├── ta.key# tls-crypt control-channel key stapled into every profile
└── client/username.ovpn# User profile with embedded CA, cert, key, and tls-crypt block
home/username/.config/OpenVPN/username-ovpn.zip# Downloadable bundle served via the 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
etc/systemd/system/openvpn-client@.service# QuickBox client tunnel template, deployed on the first install for advanced client-tunnel use

Common tasks

Routine maintenance and bundle handling through qb and systemd.

Start / stop / restart the server

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

Reinstall a user’s profile

qb reinstall vpn -u username

Typical workflows

  • Install for a user with qb; download username-ovpn.zip from webroot/username/ovpn.zip; import it into an OpenVPN client.
  • Rotate a client profile after credential changes by running qb reinstall vpn -u username to rebuild the certificate and the zip.
  • Change the server port/protocol/subnet by removing OpenVPN entirely and reinstalling the first user with the new -lp/-proto/-sub/-dns flags — these settings are fixed by the first install and inherited thereafter.
  • After firewall policy changes, verify the iptables/firewalld/ufw rules still allow your chosen port and protocol and the SNAT rule for the client subnet persists.

Managing OpenVPN from the dashboard

Once the server is installed, administrators manage OpenVPN from the dashboard’s VPN Control page (System > VPN Control, requires the admin.system.vpn permission). When both WireGuard and OpenVPN are installed, a WireGuard | OpenVPN selector appears at the top of the page; the OpenVPN tab covers server status, per-user profiles, client-tunnel management, and the server-wide gateway mode.

Server status and per-user profiles

The OpenVPN tab shows the server status card (running/installed state, subnet, and port) and a profile table listing the per-user .ovpn profiles the installer built. Administrators can view a profile’s contents (private keys and tls-crypt material are redacted on screen) — the actual downloadable bundle still comes from the nginx route described above.

Client tunnel management

Beyond the server, the dashboard manages client tunnels — the OpenVPN analogue of a WireGuard peer config. A client tunnel is a provider .ovpn the box itself dials out through, used to carry app-scoped routing. You upload your provider’s config (Mullvad, PIA, NordVPN, etc.), and the dashboard stores it in /etc/v4-dashboard/openvpn/<name>.ovpn.

ActionWhat it does
Upload
Accepts one or more .ovpn *client* configs (a server-style config is rejected). Each is validated and saved to the stash.
Activate
Starts openvpn-client@<name>.service (exclusive — stops any other active client tunnel first).
Deactivate
Stops and disables the client tunnel. Any app routing using it is torn down first.
Delete
Deactivates then removes the config from both the system and the stash.

All four actions run as background jobs — the dashboard shows a live job console while activation or upload completes.

Server tunnels vs client tunnels

The OpenVPN server (openvpn-server@server.service) accepts inbound clients connecting into your box. A client tunnel (openvpn-client@<name>.service) dials out through a remote provider so an app’s traffic egresses elsewhere. They never collide — the server is built by qb install vpn; client tunnels are uploaded and managed in the dashboard.

Gateway mode: split vs full tunnel

The OpenVPN tab exposes a server-wide gateway mode toggle that controls how much of each connected client’s traffic routes through the box. It applies to every client of the server, and only an administrator can change it.

ModeWhat it does
Split tunnel (default)
Clients reach only the server's LAN/subnet through the VPN; everything else stays on the client's own connection. This is the historic behavior — unchanged for existing installs.
Full tunnel
The client's entire outbound traffic routes out through the server (redirect-gateway), so the client's public IP becomes the server's WAN IP. Use this to run the box as a VPN gateway.

When you flip the toggle, the dashboard reconfigures the running server in place — no reinstall needed. The change lands on every client the next time it reconnects.

Full tunnel routes all client traffic

In full-tunnel mode the client’s default route is redirected through the server, so all of the client’s Internet traffic exits from the server’s IP. In split-tunnel mode only traffic destined for the server’s VPN subnet uses the tunnel. The setting is server-wide and admin-controlled.

User self-service: download and metrics

Provisioning is always done by an administrator — an admin generates a per-user client config from the dashboard (or with qb install vpn -u username) and enables app routing for that user. Once a user has been granted access to the VPN app through their ACL group, a compact self-service panel appears in their own Applications page. From it, the user can:

  • Download their own client config — the VPN row’s expansion panel shows a link to their .ovpn bundle (the same nginx basic-auth download route the installer set up). The dashboard never hands out another user’s config — the download is scoped to the signed-in user only.
  • See their routed apps, exit location, and live metrics — each app an admin has routed for that user shows its exit location, data transferred, a health indicator, and a live throughput chart while routed.
  • Toggle their own already-provisioned routes on and off — the per-route switch (labelled Routed / Direct) is the one change a non-admin may make. It only affects a route the admin already set up for that user; a user can never provision a new route, change the tunnel backend, or touch another user’s route (any such attempt is rejected).

Users never see the VPN Control page itself — that surface is admin-only. A non-admin’s only VPN surface is the self-service panel in their own VPN app row, and only when their ACL group grants them the VPN app.

App-scoped routing with OpenVPN

App-scoped routing sends a single application’s outbound traffic through a VPN tunnel while the rest of the server keeps its default route. OpenVPN is a first-class tunnel backend for this feature, alongside WireGuard. The same five applications are routable with either backend:

The app runs on the server — not on your device

App-scoped routing runs the application server-side inside a network namespace on the QuickBox box; that namespace’s egress exits through the VPN. You do not install an OpenVPN client on your own phone or laptop for app routing. The “exit location” shown is where the app’s traffic appears to originate (the provider’s exit point), not your own device.

ApplicationService
Emby
Per-user (emby-server@username)
Jellyfin
Per-user (jellyfin@username)
Plex
System-wide (plexmediaserver)
qBittorrent
Per-user (qbittorrent@username)
Dispatcharr
Per-user (4-service stack, routed together)

Choosing the OpenVPN backend

In the App-Scoped Routing card on VPN Control, expand an app and pick the Tunnel Backend — the OpenVPN option only appears once at least one OpenVPN client tunnel has been uploaded. Select an OpenVPN client config (instead of a WireGuard peer), then enable routing. The dashboard runs an openvpn-client@<config> daemon inside the app’s private network namespace and carries the app’s egress through it.

One config per routing slot

Each active routing slot needs its own independent tunnel config. An OpenVPN client tunnel that is already routing one app cannot be reused for another — upload a separate provider .ovpn per routed app. (A WireGuard peer and an OpenVPN config of the same name never conflict — the routing guards are scoped per backend.)

Kill switch and health behave the same

Kill-switch protection and automatic failback work identically for the OpenVPN backend. The health monitor watches the tunnel and, if it stalls past the configured threshold, takes the app off the network (kill switch) or attempts recovery — exactly as it does for WireGuard.

Routing is restored automatically after a reboot

App-scoped routing survives a server reboot regardless of backend. When the box comes back up, QuickBox Pro rebuilds each routing namespace and tunnel and restarts the routed services — holding each app until its namespace is ready so it does not flap, starting them in parallel without blocking the boot, and self-healing through a periodic safety-net check if a boot run stalls (worst case it converges within about 15 minutes). You never need to re-enable a routing profile after a reboot.

Plex pre-install staging

Plex registers the server with your plex.tv account during its first connection after install. To make that registration use the VPN, you can stage routing for Plex before installing it — Plex appears in the routing card even when it is not yet installed. Staging works the same whether the chosen backend is WireGuard or OpenVPN: the tunnel and namespace are set up in advance, and the Plex installer routes its claim/registration call through the namespace so plex.tv records the VPN exit IP rather than your real server IP.

After staging, install Plex from Package Management (or qb install plex -u username); the routing profile finalizes automatically. See the VPN Control and Plex docs for the full flow.

Best practices

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

Do

  • Decide the listen port, protocol, subnet, and DNS before the first install — they are set once by the first user and inherited by everyone after.
  • Use qb install vpn -u username so PKI, iptables, firewalld/ufw/SELinux, and the nginx route are configured together.
  • Protect the download route with strong htpasswd credentials and rotate them when you rotate client bundles.
  • Verify net.ipv4.ip_forward stays enabled and the tagged SNAT rule persists after firewall changes.
  • 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 the client hooks unless you know OpenVPN directives and will revalidate after changes.
  • Avoid exposing the VPN port 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.
  • Do not expect to change the server port/protocol/subnet by passing flags on a later user — remove and reinstall the first user instead.

Troubleshooting

Clients cannot connect or time out

Symptom: Connection stalls or fails to reach the server.


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

Tunnel up but no traffic

Symptom: VPN connects but cannot reach the LAN or Internet.


Checks: Ensure /etc/sysctl.d/99-ipforward.conf is present and net.ipv4.ip_forward is 1; verify the tagged SNAT rule for the client subnet 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 the /etc/htpasswd.d/htpasswd.username credentials; rerun qb reinstall vpn -u username if the route or zip is missing.

FAQ

Not in place. The server-level options (-lp, -proto, -sub, -dns) are applied only when the first user's install provisions the OpenVPN server. To change them, remove OpenVPN entirely (qb remove vpn -u username for the last user) and reinstall the first user with the new flags.
No. Subsequent users inherit the server's existing port, protocol, subnet, and DNS. Those flags only take effect on the first install that builds the server; for later users only the per-user client profile is generated.
Run qb install vpn -u newuser. The server is already built, so qb just signs a new client certificate, writes /etc/openvpn/client/newuser.ovpn, and creates the nginx download route and zipped bundle for that user.
From webroot/username/ovpn.zip. The route is backed by nginx basic auth using /etc/htpasswd.d/htpasswd.username. The downloaded username.ovpn already has the CA, certificate, key, and tls-crypt block embedded, so it imports into any OpenVPN client as-is.
Yes. Administrators can install the server from Package Management — a modal sets the listen port, protocol, client subnet, and pushed DNS, then runs qb install vpn on your behalf — or run that command directly. After install, the VPN Control page gives administrators server status, per-user profile viewing, and full client-tunnel management — upload, activate, deactivate, and delete provider .ovpn configs used for app-scoped routing. The VPN Control surface requires the admin.system.vpn permission. See Managing OpenVPN from the dashboard.
Yes. OpenVPN is a first-class tunnel backend for app-scoped routing, alongside WireGuard. Upload a provider .ovpn client tunnel in VPN Control, expand the app in the App-Scoped Routing card, choose the OpenVPN backend, and enable routing. Emby, Jellyfin, Plex, qBittorrent, and Dispatcharr are all routable through either backend. See App-scoped routing with OpenVPN.
Yes. Download your provider's OpenVPN client config (.ovpn), upload it as a client tunnel in VPN Control, then select it as the OpenVPN backend when enabling app-scoped routing for an app. The app's outbound traffic egresses through your provider while the rest of the server keeps its direct connection. The same bring-your-own-config model works for WireGuard.
Gateway mode is a server-wide, admin-controlled setting on the VPN Control OpenVPN tab. In split tunnel (the default) connected clients reach only the server's VPN subnet through the tunnel and keep their own connection for everything else. In full tunnel the client's entire outbound traffic routes through the server, so the client's public IP becomes the server's WAN IP — that turns the box into a VPN gateway. Flipping the toggle reconfigures the running server in place; the change applies to each client on its next reconnect.
Yes, if an administrator has granted them access to the VPN app through their ACL group. Provisioning itself is always admin-only (an admin generates the per-user config), but once granted, the user sees a download link for their own .ovpn bundle — and their own connection metrics for any VPN-routed apps — in the VPN row's expansion panel in their dashboard. The download is scoped to the signed-in user; no one can pull another user's config, and non-admins never see the VPN Control page.
Run qb remove vpn -u username for each user. When the last user is removed, qb revokes the certificate, purges the OpenVPN package and PKI, removes every qbx:vpn-tagged firewall rule it created, and cleans up the nginx routes and bundles. The remove path is idempotent, so a re-run after a partial removal still exits cleanly.
  • VPN Control (dashboard) — manage WireGuard and OpenVPN, peers, client tunnels, and app-scoped routing from the dashboard.
  • WireGuard — the alternative VPN backend, with the same app-scoped routing and a NordVPN config generator.
  • Let’s Encrypt — issue SSL certificates for services you expose alongside the VPN.
  • Fail2ban — protect the server’s exposed ports from brute-force attempts.

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
Last updated on
QuotasWireGuard VPN