Quickstart

Cyferio has two layers, and you can stop at either one:

1. The CLI toolkit (openvpn-install.sh + vpn-status.py) – installs and manages OpenVPN itself: adding/revoking clients, MAC-address binding, live status. Works standalone, no web app required.
2. The web admin (this repo’s app/) – a FastAPI frontend over that same CLI toolkit, for teams who’d rather click buttons than SSH in: RBAC, restrictions dashboard, reporting, a self-service portal for end users.

Requirements

• Ubuntu 18.04+, Debian 9+, AlmaLinux/Rocky/CentOS 7+, or Fedora
• Root (or passwordless sudo) to run openvpn-install.sh
• Python 3 for vpn-status.py
• Docker + the Compose plugin, only if you’re running the web admin

1. Install the CLI toolkit

1. Clone the repo and run the installer:

   git clone https://github.com/cloudlative/cyferio.git
   cd cyferio
   sudo bash openvpn-install.sh

2. The first run walks you through a normal OpenVPN server install (IP, protocol, port, DNS). Every run after that (once /etc/openvpn/server/server.conf exists) drops into a management menu instead:

   1) Add a new client
   2) List existing clients
   3) List revoked clients
   4) List MAC addresses for a client
   5) Add a MAC address for an existing client
   6) Remove a MAC address from an existing client
   7) Revoke an existing client
   8) Remove OpenVPN
   9) Show/print a client's .ovpn config
   10) Permanently delete a revoked client's leftover files
   11) Restore (reissue a new cert for) a revoked client
   12) Exit

3. Add your first client. You’ll be prompted for a name and the device’s MAC address (any common format works – aa:bb:cc:dd:ee:ff, AA-BB-CC-DD-EE-FF, aabbccddeeff, mixed case – all normalized automatically).

Device binding is on by default

Every generated .ovpn file already has push-peer-info baked in, which is what makes the MAC-address check work – a stolen or copied .ovpn alone isn’t enough to connect from a device that was never registered. See Device & Access Restrictions for how this is enforced and what else you can layer on top of it.

Check status any time with vpn-status.py – see the CLI Reference for the full flag list, JSON output, and shell completion.

2. Bring up the web admin (optional)

The web admin lives in this same repo, but docker-compose.yml and .env.example are at the repo root, not in app/ – the compose file’s bind mounts expect ./openvpn-install.sh and ./vpn-status.py at predictable, root-relative paths.

1. From the repo root, copy the env template and fill in the required values:

   cp .env.example .env

   At minimum, set SECRET_KEY, BOOTSTRAP_ADMIN_USERNAME, and BOOTSTRAP_ADMIN_PASSWORD in .env.

2. Pull and start the stack:

   docker compose pull && docker compose up -d

   The app service pulls a pre-built image from GHCR (ghcr.io/cloudlative/cyferio-app, public – no docker login needed) rather than building locally. See Deployment & Configuration for TLS/Traefik, Postgres, and how releases are versioned.

3. Log in with the bootstrap admin credentials from step 1.

   

4. You land on the dashboard – a live overview of who’s connected, client counts, MAC registrations, and rejected-connection alerts.

   

OVPN_OUTPUT_DIR must be under /etc/openvpn

That’s the only path shared between the host and the app container. If /etc/openvpn/vpn-tools.conf’s OVPN_OUTPUT_DIR is left at its script default (a human account’s home directory), generated .ovpn files are invisible to the container – every “View .ovpn” / “Email .ovpn” action fails with a “no .ovpn file found” error even though the file exists on the host. Set OVPN_OUTPUT_DIR=/etc/openvpn/client before running the app in Docker.

Next steps

• CLI Reference – every flag, JSON output, shell completion
• Device & Access Restrictions – country/city/ASN/IP/OS/bandwidth limits per client
• Roles & Permissions – RBAC and the self-service portal
• Deployment & Configuration – TLS, Postgres, releases, a fresh-machine setup script