Getting Started

mqvpn is an L3 multipath VPN built on MASQUE CONNECT-IP (RFC 9484) and Multipath QUIC.

Installation

Server

On an Ubuntu/Debian VPS, run the following to install the binary and generate a certificate, auth key, and server config.

curl -fsSL https://github.com/mp0rta/mqvpn/releases/latest/download/install.sh | sudo bash

Add --start to also start the server and register it for automatic startup on boot.

curl -fsSL https://github.com/mp0rta/mqvpn/releases/latest/download/install.sh \
    | sudo bash -s -- --start

Port and subnet can be customized with additional options.

curl -fsSL https://github.com/mp0rta/mqvpn/releases/latest/download/install.sh \
    | sudo bash -s -- --start --port 10020 --subnet 10.8.0.0/24

To uninstall, re-run the script with --uninstall (add --purge to also remove config files).

WARNING

The install script generates a self-signed certificate. Clients must use --insecure to connect. For production, replace the certificate with a trusted one (e.g., Let's Encrypt) and omit --insecure. Point --cert (or Cert / cert_file in a config file) at the full chain file (for Let's Encrypt, fullchain.pem): clients do not fetch missing intermediates.

Client (deb package)

Download the latest .deb from Releases.

# Replace VERSION and ARCH as needed (e.g., 0.6.0, amd64)
curl -LO https://github.com/mp0rta/mqvpn/releases/latest/download/mqvpn_VERSION_ARCH.deb
sudo dpkg -i mqvpn_*.deb

Windows client

Pre-built binaries are shipped for Windows amd64 and arm64. Download mqvpn_<VERSION>_windows_<ARCH>.zip from Releases, extract, and follow the bundled README.txt (admin PowerShell required).

macOS client

Pre-built binaries are shipped for Apple silicon (arm64). Download mqvpn_<VERSION>_darwin_arm64.tar.gz from Releases, extract, and follow the bundled README.txt (sudo required).

Build from source

See Building for instructions.

Quick Start

After installing the server and client, connect using the auth key and address shown by the install script.

Single path:

sudo mqvpn --mode client --server YOUR_SERVER:443 \
    --auth-key YOUR_AUTH_KEY --insecure

Multipath (multiple interfaces):

sudo mqvpn --mode client --server YOUR_SERVER:443 \
    --auth-key YOUR_AUTH_KEY --path eth0 --path wlan0 --insecure

With DNS override (prevents DNS leaks):

sudo mqvpn --mode client --server YOUR_SERVER:443 \
    --auth-key YOUR_AUTH_KEY --dns 1.1.1.1 --dns 8.8.8.8 --insecure

TIP

Without --path, the client uses the default interface (single path). Multipath requires two or more --path flags. See Multipath for details.

WARNING

The server needs its listen port open for UDP (default: 443). All client traffic is routed through the tunnel.

Generate an Auth Key

mqvpn --genkey

The install script and start_server.sh generate one automatically.

CLI Reference

mqvpn --config PATH
mqvpn --mode client|server [options]

  --server HOST:PORT     Server address (client, e.g. `[2001:db8::1]:443` for IPv6)
  --path IFACE           Multipath interface (repeatable)
  --auth-key KEY         PSK authentication
  --user NAME:KEY        Per-user PSK (repeatable, server)
  --dns ADDR             DNS server (repeatable)
  --tls-server-name NAME TLS SNI / cert verify name (client)
  --insecure             Accept untrusted certs (testing only)
  --tun-name NAME        TUN device name (default: mqvpn0)
  --listen BIND:PORT     Listen address (server, default: 0.0.0.0:443)
  --subnet CIDR          Client IPv4 pool (server)
  --subnet6 CIDR         Client IPv6 pool (server)
  --cert PATH            TLS certificate (server)
  --key PATH             TLS private key (server)
  --scheduler SCHED      Multipath scheduler: minrtt|wlb|wlb_udp_pin|backup_fec
                         (default: wlb)
  --cc ALGO              Congestion control: bbr2|bbr|cubic|none (default: bbr2)
  --mtu N                TUN MTU (1280-9000, default: auto)
  --max-clients N        Max concurrent clients (server, default: 64)
  --control-port PORT    TCP port for control API (server)
  --control-addr ADDR    Bind address for control API (default: 127.0.0.1)
  --status               Query server status via control API and exit
  --log-level LVL        Log level (debug|info|warn|error)
  --no-reconnect         Disable automatic reconnection (client)
  --kill-switch          Block traffic outside the VPN tunnel (client)
  --no-manage-routes     Do not modify the host routing table (client)
  --genkey               Generate PSK and exit
  --version              Show version and exit
  --help                 Show all options

When --config is provided, --mode is inferred from the config file. CLI arguments override config values.

Next Steps

• Building — Build from source on Linux, Windows, and Android
• Configuration — Config file reference
• Multipath — Multipath setup and scheduler options