Hardened, non-destructive OpenVPN deployment for Ubuntu/Debian VPS.
It asks exactly what it needs — server IP, verified domain or IP, TCP or UDP, port,
certificate+password or certificate-only, locked or free access, profile names
and how many users — then builds one unique .ovpn per user and applies only
the changes it owns.
Start here: Simple setup and daily-use guide — install, create profiles, download them, check status, read logs, and remove the VPN safely.
curl -fsSL https://raw.githubusercontent.com/jackh0006/OpenVPN-Wizard/main/install.sh | sudo bash
sudo vpn-installer installThe first command installs or updates the wizard. The second command starts the guided setup in your terminal; this two-step quick start is reliable over SSH.
or from a clone:
git clone https://github.com/jackh0006/OpenVPN-Wizard.git
cd OpenVPN-Wizard
sudo bash install.shYou can inspect everything first, without root or system changes:
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
vpn-installer plan --output ./vpn-plan --profiles 3That writes a complete server.conf, one client profile per user, and the
exact HAProxy block into ./vpn-plan/. It creates a throwaway PKI for the
plan only. vpn-installer plan is the safe way to check the result before
deploying.
Everything you normally need is available from one place:
sudo vpn-installer manage| What you want | Menu choice | What changes |
|---|---|---|
Make a new .ovpn file |
Add user | Only the new profile, certificate, and account |
| Stop one old device | Revoke/remove user | Only that certificate and profile |
| Give a person a new password | Change password | Only that account's password |
| Change the name shown in the VPN app | Rename profile | Only that .ovpn filename/display name |
| Replace a lost profile | Rotate certificate + key | Only that person's old key is revoked |
| Copy a profile to a phone or computer | Regenerate/export or Show download command | A fresh copy of that profile |
| See every profile | Detailed list | Nothing; read-only |
sudo vpn-installer validate # checks the running VPN
sudo vpn-installer doctor # explains common problems
journalctl -u openvpn@server -n 50 --no-pager # recent OpenVPN messagesThe installer only manages its own OpenVPN listener and clearly marked HAProxy entries. It does not stop, free, or edit ports used by another service.
sudo vpn-installer uninstall # stop and detach; keep keys/profiles
sudo vpn-installer uninstall --purge # permanently remove Wizard-owned VPN dataFull removal asks you to type REMOVE. It deletes only OpenVPN Wizard's own
files, firewall rules, and marked HAProxy entries; unrelated services stay in
place.
For a longer walkthrough with downloading and importing profiles, see the full setup guide.
| Question | Choices | Notes |
|---|---|---|
| Server public IP | IPv4 | Auto-detected, always confirmed |
| Clients connect via | domain or IP | Domain is recommended if you want TLS/Reality later |
| Public port | 1–65535 | 443 blends in with HTTPS |
| Transport | TCP or UDP | TCP can share 443 via HAProxy; UDP binds directly |
| Authentication | certificate + password or certificate only | Every user always gets a unique key |
| Access | free (full tunnel) or locked (VPN network only) | Locked adds no NAT/exit-node risk |
| IPv6 | disable (recommended) or keep enabled | Disabling prevents IPv6 leaks; it does not affect IPv4 |
| Profile prefix | e.g. MHH06 |
Used for the .ovpn filenames |
| Number of profiles | 1–50 | Each gets a separate cert, key and password |
Advanced users can also set --tun-mtu, --mssfix, --sndbuf, --rcvbuf,
--auth-digest, --tls-min, --tls-max, --internal-port,
--verify-client-cert and --duplicate-cn. The defaults match the tested
reference VPS: MTU 1400, MSS 1360, 512 KiB socket buffers, SHA384, TLS 1.3.
It also asks whether to attach the VPN to HAProxy (TCP only) and offers the optional VLESS/Reality multiplexing path.
Before any change, the wizard resolves a selected domain and shows whether it currently points to the VPS. If DNS is not ready, it asks whether to wait/use the domain anyway or automatically fall back to the server IP—no domain is required. It also inspects both TCP and UDP listeners, identifies occupied ports, and suggests free familiar alternatives. Every non-default choice is shown again for confirmation before installation.
sudo vpn-installer install --non-interactive \
--server-ip 203.0.113.10 \
--domain vpn.example.com \
--port 443 --proto tcp \
--auth userpass --access free \
--prefix MHH06 --profiles 3Profiles are named MHH06-01, MHH06-02, MHH06-03, with unique usernames,
certificates and generated passwords. Passwords are printed in the wizard and
written to /root/openvpn-wizard-credentials.txt (mode 600).
Other useful invocations:
# UDP, certificate-only, private-network-only
sudo vpn-installer install -n --server-ip 203.0.113.10 --proto udp \
--auth cert --access locked --profiles 2
# Bind directly to 443 without HAProxy
sudo vpn-installer install -n --server-ip 203.0.113.10 --no-haproxy
# Custom profile names
sudo vpn-installer install -n --server-ip 203.0.113.10 \
--users MHH06-Phone,MHH06-Laptop,TabletRun vpn-installer install --help for the complete option list.
| Component | Purpose | Public listener? |
|---|---|---|
| OpenVPN | Encrypted tunnel, AEAD ciphers, tls-crypt, per-user certificates, CRL |
Only behind HAProxy or when UDP/direct |
| HAProxy | Optional TCP port sharing (OpenVPN + TLS SNI routing) | Yes, if enabled |
| Easy-RSA | ECDSA P-384 CA, server cert, unique client certs, CRL | No |
| iptables/UFW | Only the specific allow/NAT rules required | — |
| 3X-UI | Optional VLESS/Reality multiplexing (advanced) | Loopback only |
| SQLite | User metadata and PBKDF2 password hashes | No |
Data channel: AES-256-GCM, CHACHA20-POLY1305, AES-128-GCM (AEAD)
Control: TLS 1.3 (1.2 available with --tls-min 1.2)
Control auth: tls-crypt v1 (hides and authenticates the control channel)
Certificates: ECDSA P-384, unique per user
Server pinning: verify-x509-name server name + remote-cert-tls server
Compression: disabled (avoids VORACLE-style compression oracles)
CRL: checked on every connection; revoking a user takes effect immediately
The defaults (TLS 1.3, SHA384, MTU 1400, MSS 1360, 512 KiB buffers) match
the tested reference VPS. If you need older client compatibility, run with
--tls-min 1.2. tls-crypt (v1) is used instead of tls-crypt-v2 because it
is supported by every current OpenVPN client, including OpenVPN Connect on
Android/iOS.
Profiles live in /etc/openvpn/clients/ (directory 700, files 600). Nothing
is served over plain HTTP.
scp root@YOUR_SERVER:/etc/openvpn/clients/MHH06-01.ovpn ~/Downloads/Or use the helper on your local machine:
bash scripts/download-ovpn.sh root@YOUR_SERVER MHH06-01scp root@YOUR_SERVER:/etc/openvpn/clients/MHH06-01.ovpn $env:USERPROFILE\Downloads\Or:
.\scripts\download-ovpn.ps1 -Server root@YOUR_SERVER -Profile MHH06-01Option A — Termux:
pkg install openssh
scp root@YOUR_SERVER:/etc/openvpn/clients/MHH06-01.ovpn ~/storage/downloads/Then open the file with OpenVPN Connect.
Option B — one-time HTTPS link (no SSH client needed):
sudo vpn-installer download MHH06-01 --serveThis starts a short-lived HTTPS server with a 256-bit random token, serves exactly one file once, and exits. The certificate is self-signed; accept it once in the browser.
ssh root@YOUR_SERVER 'vpn-installer download MHH06-01 --print' > MHH06-01.ovpnImport the resulting file into OpenVPN Connect (Android/iOS), OpenVPN GUI (Windows) or Tunnelblick (macOS).
This is the part most installers get wrong. v2 never rewrites your
/etc/haproxy/haproxy.cfg. Instead it:
- checks whether another frontend already binds the requested port;
- backs up the current file to
/var/backups/vpn-installer/; - appends one clearly marked block:
# >>> openvpn-wizard managed block (v2) - do not edit >>> frontend ovpn_wizard_frontend_443 bind *:443 ... backend ovpn_wizard_openvpn server openvpn 127.0.0.1:<internal-port> # <<< openvpn-wizard managed block <<<
- runs
haproxy -c -f …before reloading; - restores the previous file automatically if validation or reload fails.
On later runs it replaces only that block. vpn-installer uninstall
removes only that block. To detach the VPN manually, delete the marked
block and reload HAProxy.
If another service already owns the port, the installer refuses to proceed
and tells you exactly which line/process is responsible. It never kills or
reconfigures unrelated services. Use --port 8443, --proto udp, or free the
port yourself.
- Opens only the VPN public port (
tcporudp) and preserves existing rules. - Adds NAT/forwarding only in free mode. Locked mode deliberately adds no NAT, so the VPS cannot be used as an internet exit node.
- Never runs
ufw resetand never flushes iptables. IPv6 is disabled only when you choose that option. - Writes
/etc/sysctl.d/99-openvpn-wizard.conf; enables BBR only when the kernel module is actually available. - Persists rules with
netfilter-persistentwhen present, otherwise withiptables-saveinto the existing/etc/iptables/rules.v4.
sudo vpn-installer manage # add, revoke, rename, rotate, export
sudo vpn-installer validate # re-run all checks
sudo vpn-installer doctor # explain problems and exact fixes
sudo vpn-installer download # list profiles / show download options
sudo vpn-installer uninstall # detach safely (keeps keys unless --purge)Use sudo vpn-installer uninstall --purge for a full removal of Wizard-owned
VPN data. It requires typing REMOVE and removes only the marked HAProxy
entries created by OpenVPN Wizard.
Management actions:
| Action | Effect |
|---|---|
| Add user | New unique certificate/key + profile; old users untouched |
| Revoke user | Adds cert to CRL, reloads OpenVPN, deletes the profile |
| Change password | Updates PAM and the hash in SQLite |
| Rename profile | Renames the .ovpn; certificate is unchanged |
| Rotate keys | Revokes the old cert and issues a new key pair |
| Export | Re-renders and validates the profile |
The SQLite database stores PBKDF2 hashes and metadata only. It never stores private keys or plaintext passwords.
v2.1 was checked read-only against a working Ubuntu 22.04 VPS running OpenVPN
on 127.0.0.1:11944 behind an existing HAProxy frontend on *:443. The
planner detected the existing bk_ovpn route and reported action: reuse; applying the manager to a copy of the live config returned the
same SHA-256, so HAProxy was untouched. A profile generated from the existing
PKI completed a TLS 1.3 handshake and certificate verification (CN=ChangeMe)
against the live server. Details: docs/LIVE-VERIFICATION.md.
- Traffic between client and VPS is encrypted and authenticated with modern
AEAD ciphers,
tls-crypt, and unique ECDSA certificates. - TCP/443 makes the connection look like HTTPS at the port level. A determined DPI system that blocks unknown protocols can still identify OpenVPN; no OpenVPN configuration can guarantee invisibility. The optional VLESS/Reality path is the stronger anti-DPI option.
- A VPS operator can always observe metadata (connection times, volume) and, because the VPN terminates there, traffic in principle. Use a provider you trust.
- TCP inside TCP can reduce throughput on lossy links. Use UDP if speed matters and the network allows it.
- IPv6 is disabled by default (matching the reference VPS) and clients are
told to block it. Use
--enable-ipv6if you need host IPv6; the tunnel itself is IPv4-only, so judge whether that is appropriate for your network. - Treat
.ovpnfiles as private keys. Usescp/the one-time token server, never email or chat. Revoke and rotate if one leaks.
- Ubuntu 22.04/24.04 or Debian 12 (x86_64 or arm64)
- Root access
- A public IPv4 address
- For domain mode: a DNS A/AAAA record pointing at the VPS
- Ports: the chosen VPN port (443 by default); port 80 only if you enable Let's Encrypt for the optional VLESS listener
v1 hardcoded credentials and replaced the entire HAProxy config. v2 does neither. Before upgrading:
- Keep a copy of the current profiles.
- Run
sudo vpn-installer install(v2). If it detects the exact v1 HAProxy layout, it backs it up and migrates to the append-only layout — the backup path is printed. - Existing PKI at
/etc/openvpn/pki,/etc/openvpn/easy-rsa/pkior/root/easy-rsa/pkiis reused when healthy, so current profiles keep working. The existing TLS-crypt key, certificate CN, port, ciphers, TLS version, MTU and socket buffers are detected and preserved automatically. - Re-download profiles for the new users. v1 tls-crypt-v2 clients are
converted to standard
tls-cryptonly for newly generated profiles; do not delete the old.ovpnfiles until the new ones are tested.
If anything looks wrong, run sudo vpn-installer doctor and read the full log
at /var/log/vpn-installer/install.log.
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest -q
vpn-installer plan --output /tmp/vpn-planThe test suite renders real certificates and profiles, checks certificate/key
matching, verifies HAProxy merge idempotency, and asks the real openvpn
binary to parse every generated configuration when it is installed.
Optional crypto donations are welcome. The same public addresses are used in the author's other repositories. Full details and network warnings: DONATIONS.md.
| Asset | Address |
|---|---|
| Bitcoin (BTC) | bc1q8t0fn2yrsy4lh3m0pz34uj27t8vxjeavkjym83 |
| Ethereum / BNB / USDT-USDC EVM | 0xdad428900a4359be8f76b3062df34211582e09eb |
| TRON / USDT TRC-20 | TMpb6RNTuGNM1eTakm9kjds1mRTPYYJesf |
| Solana / USDT-USDC SPL | BDCCrRez1yD1RpkAtiqKKDk3BfxPD8P7nkL26jCYrzgL |
| Litecoin (LTC) | ltc1q2gs89cfy3mumr7gu9w0zl9rllf80q67m5rmma8 |
Use the exact address from DONATIONS.md. Never send on the wrong network; crypto transfers are irreversible.
MIT. Made by jackh0006 · jackh109867@gmail.com. No telemetry, no tracking, no phone-home.