PUQ Mautic

PUQVPNCP

PUQVPNCP v2.3 — High-performance Multi-Protocol VPN Control Panel with WireGuard, AmneziaWG (anti-censorship DPI bypass), OpenVPN, and IKEv2/IPsec support. Developed and maintained by PUQ Software. Free for up to 50 users with 170+ REST API endpoints. Official website: https://puqvpncp.com

00. Changelog

v2.3.0 — September 2026

Major release — AmneziaWG anti-censorship stealth WireGuard protocol, strict protocol package validation, reactive multi-tab network interface, and expanded REST API.

AmneziaWG Protocol Support (Anti-Censorship & DPI Bypass)

Full integration of AmneziaWG — a modified WireGuard protocol engineered to evade Deep Packet Inspection (DPI) and strict firewall censorship:

Protocol Package Validation & Safety

Prevents enabling VPN protocols whose underlying system packages are not installed:

Reactive Multi-Tab Network Interface

Seamless AJAX experience when managing networks with multiple VPN protocols:

REST API & OpenAPI 3.0.3 Expansion

v2.1.1 — March 2026

Patch release — client bandwidth fix and OpenVPN session stability improvements.

Client Bandwidth Fix

Fixed an issue where per-client bandwidth limits were ignored during client creation:

OpenVPN Session Stability

Client operations (add, edit, delete) no longer restart the OpenVPN server, preserving all active sessions:

Documentation

v2.1.0 — March 2026

Feature release — DNS-based ad blocking for all VPN clients, plus stability improvements.

DNS Ad Blocking

Built-in ad and tracker blocking via bind9 Response Policy Zone (RPZ):

Metric Value
Default blocked domains ~130,000+
With all lists enabled ~250,000+
Update frequency Every 24 hours
Supported formats hosts, domain-per-line, wildcard, adblock filter

New API endpoints:

Method Endpoint Description
GET /dns/adblock Get ad blocking configuration
PUT /dns/adblock Enable/disable, toggle lists
POST /dns/adblock/update Force update block lists
POST /dns/adblock/lists Add custom block list
DELETE /dns/adblock/lists/{name} Delete custom list
GET /dns/adblock/whitelist List whitelisted domains
POST /dns/adblock/whitelist Add domain to whitelist
DELETE /dns/adblock/whitelist/{name} Remove from whitelist

DNS Page Redesign

The DNS configuration page now uses a tabbed layout:

OpenVPN Startup Fix

Fixed a race condition where OpenVPN clients could lose internet connectivity after server restart:

Other Improvements

v2.0.0 — March 2026

Major release — complete rewrite with new architecture, third VPN protocol, and dozens of new features.

New Architecture: Network → Client → Protocol

The core data model has been redesigned from the ground up:

This architecture allows running multiple isolated VPN networks on a single server, each with completely different configurations.

OpenVPN Support

PUQVPNCP now supports three VPN protocols simultaneously:

Protocol New in v2.0
WireGuard Updated — now per-network
OpenVPN New — full support with PKI, certificates, custom config
IKEv2/IPsec Updated — now per-network

OpenVPN features include:

Upstream WireGuard Tunnels

Route network traffic through external WireGuard VPN servers:

Diagnostics & Environment Integrity

New real-time diagnostics system for monitoring server health:

Per-Network Firewall

Each network now has its own firewall chain set:

Role-Based Access Control (RBAC)

Fine-grained permission system replacing the old single-admin model:

Traffic Control & Bandwidth

Per-network and per-client bandwidth management:

Network Peering

Allow communication between VPN networks on the same server:

Self-service configuration links for all three protocols:

REST API Expansion

The API has been completely rewritten and expanded:

Metric v1.x v2.0
Endpoints ~30 148+
Documentation None OpenAPI 3.0
Authentication Single hash Bearer tokens + RBAC
Swagger UI No Yes (/api_docs)

New API areas: Networks, Clients, OpenVPN, Upstreams, Peering, Firewall, Diagnostics, Permission Groups, System Users, Profile management.

UI & Theme

Other Improvements

Migration from v1.x

PUQVPNCP v2.0 is a ground-up rewrite and is not directly upgradeable from v1.x. Key differences:

Aspect v1.x v2.0
Architecture Account → WireGuard Server Network → Client → Protocol
Protocols WireGuard + IKEv2 WireGuard + OpenVPN + IKEv2
Auth Single admin + API hash Multi-user + RBAC + API tokens
Firewall Global rules Per-network chains
API ~30 endpoints, no docs 148+ endpoints, OpenAPI 3.0
UI jQuery + page reloads Bootstrap 5 + AJAX

For migration assistance, see Troubleshooting or contact PUQ Support.

01. Description

Overview

PUQVPNCP is a comprehensive VPN server management panel that supports four VPN protocols simultaneously: WireGuard, AmneziaWG, OpenVPN, and IKEv2/IPsec. It provides a modern web interface for managing VPN networks, clients, firewall rules, traffic control, and monitoring — all from a single dashboard.

The panel is designed for VPN service providers, hosting companies, and system administrators who need to manage hundreds or thousands of VPN clients across multiple networks with fine-grained control over bandwidth, routing, and anti-censorship security.

Key Features

Multi-Protocol Support

PUQVPNCP is unique in supporting four VPN protocols at once on the same server:

Protocol Technology Best For
WireGuard Modern kernel-level VPN Speed, low latency, mobile devices
AmneziaWG Obfuscated WireGuard fork Evading Deep Packet Inspection (DPI), strict censorship, ISP blocking
OpenVPN Battle-tested SSL/TLS VPN Compatibility, restrictive networks
IKEv2/IPsec Native OS support (strongSwan) iOS, macOS, Windows — native connection, no app required

Each client can connect via any enabled protocol using the same IP address. The panel automatically generates configuration files, QR codes, and certificates for each protocol.

Network Architecture

                   +--------------------------------------+
                   |          PUQVPNCP Server             |
                   |                                      |
Internet <---------|  Network A (10.0.0.0/24)             |
                   |    |-- WireGuard  (wg51820)          |
                   |    |-- AmneziaWG  (awg51821)         |
                   |    |-- OpenVPN    (ovpn1197)         |
                   |    +-- IKEv2      (strongSwan)       |
                   |                                      |
Upstream VPN <-----|  Network B (10.100.1.0/24)           |
(wgup0)            |    |-- WireGuard  (wg51822)          |
                   |    |-- AmneziaWG  (awg51823)         |
                   |    |-- OpenVPN    (ovpn1198)         |
                   |    +-- IKEv2      (strongSwan)       |
                   |                                      |
                   |  Network C (10.100.2.0/24)           |
                   |    +-- ...                           |
                   +--------------------------------------+

Upstream Tunnels

Route client traffic through external WireGuard VPN servers for:

Per-Network Control

Each network operates independently with its own:

Security & Access Control

Operations

Navigation

The web interface is organized into dropdown menus:
Networks menu Clients menu VPN Servers menu Settings menu
Networks Clients VPN Servers Settings

Technical Specifications

Component Details
OS Debian 12/13, Ubuntu 22.04+
Protocols WireGuard, AmneziaWG, OpenVPN 2.6+, IKEv2 (strongSwan 6.x)
Web Interface HTTPS with Let's Encrypt auto-SSL
API REST API, 170+ endpoints, OpenAPI 3.0
DNS Built-in bind9 DNS server
Firewall iptables/ip6tables with ipset
Monitoring rsyslog + telegraf + InfluxDB
Themes Light / Dark / Auto (system)
Max Clients 16,383 per server (across all networks)
Binary Single ~34MB Go binary, no runtime dependencies

Architecture Overview

+-----------------------------------------------------------------+
|                        Web Interface                            |
|                  (Bootstrap 5, jQuery, AJAX)                    |
+-----------------------------------------------------------------+
|                        REST API (Gin)                           |
|                   170+ endpoints, OpenAPI                       |
+-----------------------------------------------------------------+
|                       Core Engine (Go)                          |
|  +----------+ +-----------+ +---------+ +---------+ +---------+ |
|  |WireGuard | | AmneziaWG | | OpenVPN | | IKEv2   | |Firewall | |
|  |  (wg)    | |   (awg)   | |(openvpn)| |(strgSwn)| |(iptables)|
|  +----------+ +-----------+ +---------+ +---------+ +---------+ |
|  +----------+ +-----------+ +---------+ +---------+ +---------+ |
|  |Upstreams | |    DNS    | |   TC    | |Monitoring| |   OTL  | |
|  | (wgupN)  | |  (bind9)  | |  (tc)   | |(telegraf)| |(tokens)| |
|  +----------+ +-----------+ +---------+ +---------+ +---------+ |
+-----------------------------------------------------------------+
|                      Linux Kernel                               |
|   WireGuard / AmneziaWG module, Netfilter, TC, iproute2         |
+-----------------------------------------------------------------+

WHMCS Billing & Provisioning Automation

Selling VPN services or hosting packages? PUQ Software provides an official provisioning module for WHMCS:

PUQVPNCP WHMCS Provisioning Module

Key Capabilities:

License

PUQVPNCP requires an active license. Licenses can be purchased at:

https://puqcloud.com/store/puqvpncp

The license defines the maximum number of VPN clients and is validated periodically through the PUQ Cloud license server.

02. Installation

System Requirements

Requirement Minimum
OS Debian 12/13 or Ubuntu 22.04+ (amd64)
CPU 1 core (2+ recommended for 500+ clients)
RAM 512 MB (2+ GB recommended)
Disk 1 GB free space
Network Public IPv4 address, root access

Required Packages

The panel automatically manages its dependencies, but the following packages must be available in the system repositories:

Category Packages
VPN Protocols wireguard, wireguard-tools, amneziawg-dkms, amneziawg-tools, openvpn, easy-rsa, strongswan, strongswan-pki
Network & Firewall iproute2, iptables, ipset
DNS bind9, bind9-utils
Monitoring rsyslog, telegraf
Security openssl
Utilities procps, uuid-runtime, bash, grep, gawk

Note: You can verify all dependencies after installation using Settings > Environment page.

Installation

Step 1: Download

Download the latest .deb package:

wget https://puqvpncp.com/download/puqvpncp_latest_amd64.deb

All versions are available at: https://puqvpncp.com/download/

Step 2: Install Dependencies

apt update && apt install -y wireguard wireguard-tools openvpn easy-rsa \
  strongswan strongswan-pki iproute2 iptables ipset \
  bind9 bind9-utils rsyslog telegraf openssl \
  procps uuid-runtime bash grep gawk

Optional: AmneziaWG (Anti-Censorship DPI Bypass)

To enable AmneziaWG, install the kernel module and tools for your distribution:

Debian 12 (Bookworm):

On Debian 12, the Ubuntu 22.04 (jammy) PPA must be used because Debian 12 has glibc 2.36, whereas packages from noble require libc6 >= 2.38. The keyring is saved directly in .asc format without needing gpg:

apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu jammy main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Debian 13 (Trixie):

On Debian 13, use the Ubuntu 24.04 (noble) PPA:

apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu noble main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Ubuntu (22.04 / 24.04 LTS):

add-apt-repository -y ppa:amnezia/ppa
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Alternative on Ubuntu (without add-apt-repository):

mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Verify AmneziaWG installation:

dkms status            # Should output: amneziawg/..., ...: installed
lsmod | grep amneziawg # Should display loaded kernel module
awg --version          # Should display awg tools version

Tip: If the kernel module failed to compile or after a kernel update, run:

apt-get install -y build-essential dkms linux-headers-$(uname -r) && dpkg-reconfigure amneziawg-dkms && modprobe amneziawg

Step 3: Install PUQVPNCP

dpkg -i puqvpncp_latest_amd64.deb

This will:

Step 4: Start the Service

systemctl start puqvpncp

Step 5: Access the Web Interface

Open your browser and navigate to:

http://<your-server-ip>:8098

Default credentials:

Field Value
Username admin
Password admin

Important: Change the default password immediately after first login via Settings > System Users.

Login page Login page -- enter your username and password

Configuration File

The main configuration file is located at /etc/puqvpncp/puqvpncp.conf. It is created automatically on first start with default values. Format: Key=Value, one per line. Lines starting with # are comments.

# The port on which the WWW server will be set up. (Default: 8098)
WebPort=8098

# The IPv4 or IPv6 on which the WWW server will be set up. (Default: 0.0.0.0)
WebIP=0.0.0.0

# The IPv4 or IPv6 address from which you can login to the web console.
# Supports multiple IPs delimited by comma. (Default: 0.0.0.0)
AllowedWebIP=0.0.0.0

# Directory for log files (Default: /var/log/puqvpncp/)
LogDir=/var/log/puqvpncp/

# Directory for data files (Default: /usr/local/puqvpncp/)
DataDir=/usr/local/puqvpncp/

# SSL certificate support Let's Encrypt yes/no (Default: no)
# If this option is enabled, then the panel is accessible on the standard port 443.
# The port in the non-ssl protocol is not serviced
LetsEncrypSSL=no

# Domain for SSL certificate generation
# Be sure to check that the domain resolves the IP address of this server
Domain=

# Remove tabs in the Wireguard client configuration.
# Sometimes necessary to support non-official Wireguard clients.
DeleteTabsFromConfig=no

# Session timeout in minutes (Default: 720)
SessionTimeout=720

# Log level: INFO, WARN, ERROR, DEBUG (Default: INFO)
LogLevel=INFO

# Trusted proxy IPs (comma-separated). Leave empty for default Gin behavior.
# Set to 'none' to trust no proxies.
TrustedProxies=

# HTTP request timeout in seconds (Default: 30)
HttpTimeout=30
Parameter Default Description
WebPort 8098 Web interface port. Ignored when LetsEncrypSSL=yes (uses 443)
WebIP 0.0.0.0 Listen address (IPv4 or IPv6)
AllowedWebIP 0.0.0.0 Restrict access to specific IPs (comma-separated). 0.0.0.0 = allow all
LogDir /var/log/puqvpncp/ Log files directory
DataDir /usr/local/puqvpncp/ Application data directory (networks, clients, configs)
LetsEncrypSSL no Enable Let's Encrypt SSL (yes/no). Requires Domain to be set
Domain (empty) Domain for SSL certificate. Must resolve to this server's IP
DeleteTabsFromConfig no Remove tabs from WireGuard client configs (for non-official clients)
SessionTimeout 720 Web session timeout in minutes (12 hours)
LogLevel INFO Logging verbosity: DEBUG, INFO, WARN, ERROR
TrustedProxies (empty) Comma-separated proxy IPs. none = trust no proxies
HttpTimeout 30 HTTP request timeout in seconds

After enabling LetsEncrypSSL=yes and setting Domain, restart the service. The web interface switches to port 443 (HTTPS) and obtains a certificate automatically.

Update

Step 1: Download the New Version

wget https://puqvpncp.com/download/puqvpncp_latest_amd64.deb

Step 2: Stop the Service

systemctl stop puqvpncp

Important: The service must be stopped before updating. The binary cannot be overwritten while it is running.

Step 3: Install the Update

dpkg -i puqvpncp_latest_amd64.deb

Step 4: Start the Service

systemctl start puqvpncp

Your configuration and data are preserved during updates.

Uninstallation

systemctl stop puqvpncp
apt remove puqvpncp

Note: Uninstalling the package does not remove your configuration (/etc/puqvpncp/) or data (/usr/local/puqvpncp/). Remove them manually if needed.

03. Initial Setup

After installing PUQVPNCP, follow these steps to configure the server for production use.

Step 1: Activate the License

  1. Navigate to Settings > License
  2. Enter your license key
  3. Click Save

License page License page — enter your license key

After activation, the license status will show Valid with the expiration date.

License valid License activated successfully

Purchase a license: https://puqcloud.com/store/puqvpncp

Step 2: System Configuration

Navigate to Settings > System to configure the core settings.

System configuration System configuration page

General Settings

Setting Description Default
Traffic collection (min) How often traffic counters are read from iptables 1
Traffic history (months) How long traffic data is retained 2
Max bandwidth (Mbit/s) Global server bandwidth limit for TC 10000
WG handshake uptime (s) Client considered offline after this many seconds without a WireGuard handshake 180
AWG handshake uptime (s) Client considered offline after this many seconds without an AmneziaWG handshake 180

VPN Domain

Set the VPN Domain field (e.g., vpn.example.com) to use a domain name instead of IP in client configurations. This way, if you change your server IP, clients will not need to be reconfigured.

Tip: Point your domain's A record to the server IP before setting this field.

Security

Setting Description
Redirect URL URL to redirect unauthorized web access attempts
Max login attempts Lock the account after N failed attempts (0 = disabled)
Lockout time (min) How long the account is locked
robots.txt Content for /robots.txt (blocks search engines by default)

Panel

Setting Description
Panel title Browser tab title
Default theme Auto (system) / Light / Dark
Maintenance mode Block all pages except login

Step 3: Enable SSL (Let's Encrypt)

  1. Ensure your domain points to the server IP (DNS A record)
  2. Go to Settings > System
  3. In the SSL / Let's Encrypt section, set:
    • Enabled = Yes
    • Domain = your domain (e.g., vpn.example.com)
    • Email = your email for Let's Encrypt notifications
  4. Click Save and then Reload

After reload, the web interface will be available on https://your-domain.com (port 443).

Step 4: Configure Networking

Navigate to Settings > Networking to manage server network interfaces and routes.

Networking interfaces Network interfaces list

Danger Zone. Incorrect network configuration may make the server unreachable. After applying changes you will have 45 seconds to confirm. If not confirmed, the previous configuration will be restored automatically.

Adding an Interface

Click the + button to add a new interface (alias or VLAN).

Add interface Add network interface dialog

Applying Configuration

After making changes, click Apply. A confirmation dialog warns about the 45-second timeout:

Apply confirmation Apply configuration confirmation — 45-second safety timeout

Once applied, you must confirm within the timeout or changes will be reverted:

Apply countdown Configuration applied — confirm within 45 seconds or changes will be reverted

Routes

Switch to the Routes tab to view the current routing table.

Routes table System routing table (live)

Step 5: Environment Check

Navigate to Settings > Environment to verify all required packages are installed.

Environment check Environment check — VPN protocols section

The page shows:

Environment check — DNS, Monitoring, Security Environment check — DNS, Monitoring, and Security sections

Missing packages are highlighted and can be installed using the copy button.

Step 6: Configure Firewall

Navigate to Settings > Firewall to set up global firewall policies.

Firewall settings Firewall settings — global policies

Setting Description
Forwarding (NAT) Enable/Disable NAT for VPN clients
INPUT policy Default action for incoming packets
FORWARD policy Default action for forwarded packets
OUTPUT policy Default action for outgoing packets

Important: Keep Forwarding (NAT) enabled for VPN clients to access the internet.

Step 7: Configure DNS

Navigate to Settings > DNS to configure the built-in bind9 DNS server.

DNS configuration DNS server configuration

Set the Forwarders field to upstream DNS servers (e.g., 8.8.8.8, 8.8.4.4). This allows VPN clients to use the server as their DNS resolver.

Next Steps

After completing the initial setup:

  1. Create a Network — define your first VPN network with a subnet
  2. Add Clients — create VPN client accounts
  3. Configure VPN Protocols — set up WireGuard, AmneziaWG, OpenVPN, or IKEv2

04. Dashboard

The Dashboard is the main landing page after login. It provides a complete overview of the server status, VPN protocols, and services.

Dashboard overview PUQVPNCP v2.3 Dashboard — Server info, system status, 4 VPN protocols (WireGuard, AmneziaWG, OpenVPN, IKEv2), and services

Server Information

Server information card Server information card

Field Description
Hostname Server FQDN
OS Operating system and architecture
CPU Processor model and thread count
CPU Load 1 / 5 / 15 minute load averages
Memory Used / total with percentage bar
Timezone Server timezone

PUQVPNCP Status

PUQVPNCP status card PUQVPNCP status card

Field Description
Status OK = fully loaded, Loading = starting up
Version Current software version
Networks Total number of configured networks
Clients Active clients / license limit
License Validity status and expiration date

Quick action buttons:

VPN Protocols

VPN protocol cards Four VPN protocol status cards: WireGuard, AmneziaWG, OpenVPN, IKEv2

Each protocol card displays:

Field Description
Version / Package Installed package version (wireguard, amneziawg, openvpn, strongswan)
Enabled ON/OFF operational status
Encryption / Obfuscation Cryptographic cipher or obfuscation mode (e.g., Curve25519, DPI Bypass)
Networks Number of networks with this protocol enabled
Clients Total clients configured across those networks
Online Currently connected active peers/sessions

Click Configure on any card to go directly to that protocol's global settings page.

Services

Services details Service cards with detailed configuration info

Firewall

DNS Server

Monitoring

Backups

05. Networks

Networks are the core organizational unit in PUQVPNCP. Each network defines a VPN subnet with its own protocol settings, firewall rules, bandwidth limits, and upstream routing.

Networks List

Navigate to Networks > List of networks to see all configured networks.

Networks list Networks list — shows protocols, IP, upstream, and bandwidth for each network

The table displays:

Column Description
Name Network identifier
Clients Number of client accounts
WireGuard / OpenVPN / IKEv2 Protocol enabled status (ON/OFF)
Network Subnet CIDR
IP Server IP for the network
Upstream Internet exit point (direct IP or WireGuard tunnel)
Bandwidth Download/Upload limits in Mbit

Creating a Network

Navigate to Networks > Add network or click the + button.

Create network Create a new network

Required Fields

Field Description Example
Name Unique network name (alphanumeric + underscore) office_vpn
Subnet (IPv4 CIDR) Network subnet 10.0.0.0/24
WireGuard IP Server IP for WireGuard interface 10.0.0.1
OpenVPN IP Server IP for OpenVPN interface 10.0.0.254
IKEv2 IP Server IP for IKEv2 10.0.0.253

Optional Fields

Field Description
Description Free-text description
Upstream Select internet exit: server IP (direct) or WireGuard upstream tunnel
VPN Domain Override the global VPN domain for this network
DNS 1 / DNS 2 DNS servers pushed to VPN clients
Bandwidth Download / Upload Network-wide bandwidth limit (Mbit, 0 = unlimited)
Disable NAT Disable SNAT for this network (for bridged setups)
Client-to-Client Allow clients within the same network to communicate
IPv6 Enable IPv6 dual-stack

Note: VPN protocols (WireGuard, AmneziaWG, OpenVPN, IKEv2) can be enabled after creating the network.

Editing a Network

Click the edit button on any network to open the tabbed editor.

Main Tab

Network edit — Main Network edit — Main tab with protocols, actions, and traffic overview

Network Protocols Card Protocols selector — WireGuard, AmneziaWG, OpenVPN, IKEv2

The Main tab shows:

WireGuard Tab

Network edit — WireGuard Network edit — WireGuard tab

Field Description
Listen Port WireGuard UDP port for this network
Allowed IPs Allowed IPs for peers (empty = use global 0.0.0.0/0)
MTU Tunnel MTU (0 = use global setting)
Persistent Keepalive Keepalive interval in seconds (0 = use global)
Interface Auto-generated WireGuard interface name (e.g., wg51823)
Policy Routing Mark/Table values and CONNMARK rules (auto-configured)
Private / Public Key WireGuard key pair. Can be regenerated or derived.

AmneziaWG Tab

Network edit — AmneziaWG Network edit — AmneziaWG tab with obfuscation parameters and interface info

Field Description
Listen Port AmneziaWG UDP port for this network
Allowed IPs Allowed IPs for peers (empty = use global 0.0.0.0/0)
MTU Tunnel MTU (0 = use global setting)
Persistent Keepalive Keepalive interval in seconds (0 = use global)
Interface Auto-generated AmneziaWG interface name (e.g., awg51821)
Magic Headers (H1–H4) Custom or randomized packet headers to bypass DPI
Junk Packet Controls Jc count, Jmin/Jmax size range, and S1/S2 junk sizes
Private / Public Key Key pair for AmneziaWG encryption

OpenVPN Tab

Network edit — OpenVPN Network edit — OpenVPN tab

Field Description
Port OpenVPN port for this network
Protocol UDP or TCP
Interface Auto-generated interface name (e.g., ovpn1197)
Policy Routing Mark/Table and CONNMARK (auto-configured)
Client Push Full or split tunnel, DNS settings
Per-Network Overrides Cipher, Auth Digest, Compression, MTU, MSS Fix

IKEv2 Tab

Network edit — IKEv2 Network edit — IKEv2 tab

Field Description
Enabled IKEv2 enabled for this network
Ports 500 / 4500 UDP (standard IPsec)
Per-Network Overrides ESP, IKE proposals, lifetimes, DPD settings

Port Forwarding Tab

Port forwarding Network edit — Port Forwarding tab

Create DNAT rules to forward external ports to specific VPN clients. Each rule maps an external port to a client IP and destination port.

Routes Tab

Custom routes Network edit — Routes tab

Define custom routes that are pushed to VPN clients. Each route specifies a destination CIDR and description. Useful for split-tunnel configurations.

Firewall Tab

Network firewall Network edit — Firewall tab

Per-network firewall rules organized by type:

Mangle rules Network edit — Mangle rules for traffic control

Clients Tab

Network clients Network edit — Clients tab

Lists all clients in this network with their name, username, IP, status, and bandwidth.

Traffic Control Tab

Traffic control Network edit — Traffic Control tab (upload classes)

Real-time traffic control statistics showing TC classes for each client and direction:

Traffic control download Traffic Control — download classes

Traffic Tab

Network traffic Network edit — Traffic tab with monthly chart and daily breakdown

Monthly traffic statistics with:

06. Clients

Clients are VPN accounts assigned to a network. Each client gets a unique IP address, WireGuard keys, OpenVPN certificate, and IKEv2 credentials — and can connect via any protocol enabled on their network.

[!TIP] Automating Client Management with WHMCS: Instead of manually creating and managing clients, you can automate account provisioning, suspension, cancellation, and configuration delivery using the official PUQVPNCP WHMCS Provisioning Module.

Clients List

Navigate to Clients > List of clients.

Clients list Clients list with name, username, network, IP, status, and bandwidth

Column Description
Name Client identifier
Username VPN login username (for OpenVPN/IKEv2)
Network The network the client belongs to
IP Assigned IPv4 address (and IPv6 if enabled)
Status Enable/Disable
Bandwidth Download / Upload limits

Adding a Client

Navigate to Clients > Add client or click the + button.

Add client Add a new client

Field Description
Name Unique client name
Username Login for OpenVPN and IKEv2 authentication
Password Auto-generated or custom. Click the key icon to generate.
Status Enable or Disable the account
Bandwidth Download / Upload (Mbit) Per-client speed limit (0 = use network default)
Network Select the target network
IP Address Select from available IPs in the subnet

Editing a Client

Click edit on any client to open the tabbed editor.

Main Tab

Client edit — Main Client edit — Main tab with traffic control and statistics

The Main tab shows:

Network &amp; IP card Network & IP card — shows the assigned network and IP address

Client bandwidth and TC classids Bandwidth settings with TC class identifiers

The TC line below bandwidth fields shows the traffic control class IDs used for this client (e.g., TC: 1:4111 / 1:6111 for download IPv4/IPv6).

Traffic Control Card

Traffic control card Real-time traffic control with bandwidth graph

The Traffic Control card provides:

Traffic Statistics

Traffic statistics Monthly traffic statistics

From the Main tab, click Create in the One-Time Link section to generate a self-service configuration URL.

The link allows the end user to download their VPN configuration files, QR codes, and credentials without admin panel access. See One-Time Links for details.

WireGuard Tab

Client WireGuard Client edit — WireGuard tab

Displays:

AmneziaWG Tab

Client AmneziaWG Client edit — AmneziaWG tab with keys and QR code

Displays:

OpenVPN Tab

Client OpenVPN Client edit — OpenVPN tab

Displays:

IKEv2 Tab

Client IKEv2 Client edit — IKEv2 tab

Displays:

Traffic Tab

Client traffic Client edit — Traffic tab with chart and daily breakdown

Monthly traffic view with:

Clients Online

Navigate to Clients > Clients online to see currently connected VPN users across all protocols.

The page shows a unified view of:

Each entry displays the client name, protocol, IP address, and connection duration.

07. WireGuard

Overview

WireGuard is a modern, high-performance VPN protocol built into the Linux kernel. It is the fastest protocol supported by PUQVPNCP, offering:

WireGuard is ideal for mobile devices, low-latency applications, and high-throughput scenarios.

Need Anti-Censorship or DPI Bypass? If standard WireGuard packets are detected or throttled by deep packet inspection (DPI) firewalls, use AmneziaWG — a specialized WireGuard fork with header obfuscation and junk packet injection.

Requirement: wireguard and wireguard-tools packages must be installed. Check via Settings > Environment.

Navigate to VPN Servers > WireGuard to access WireGuard management. The page has 5 tabs: Overview, Networks, Settings, Online, Client Profiles.

Overview Tab

WireGuard overview WireGuard overview — service status, summary, online connections

The Overview tab shows:

Card Description
Service Status Installed wireguard and wireguard-tools package versions
Summary Total number of WireGuard networks and clients
Online Connections Number of currently active WireGuard connections with a link to view all

Networks Tab

WireGuard networks WireGuard networks — list of all WireGuard interfaces

Shows all networks that have WireGuard enabled:

Column Description
Name Network name (link to network edit page)
Clients Number of WireGuard clients in this network
Interface WireGuard interface name (e.g., wg51820)
Network Subnet assigned to this network
Endpoint Server IP and UDP port for client connections
Bandwidth Upload / download bandwidth limits

Each network has its own WireGuard interface with independent settings. See the Networks page for per-network WireGuard configuration.

Settings Tab

WireGuard settings WireGuard settings — client profile defaults

Configure global defaults for WireGuard client profiles. These settings are applied to all WireGuard client configs unless overridden at the network level.

Setting Description Default
MTU Tunnel MTU (0 = system default) 1420
Persistent Keepalive (sec) Keepalive interval (0 = disabled) 25
Allowed IPs Controls which traffic goes through VPN. Empty = full tunnel (0.0.0.0/0). Networks with custom routes use split-tunnel regardless of this setting (empty)

Use the Restore defaults button to reset all settings to their original values.

Online Tab

WireGuard online WireGuard online users — currently connected peers

Shows all WireGuard peers with a recent handshake:

Column Description
Name Client name (link to client page)
Status Enable/Disable
Username System user who owns this client
AllowedIPs Client's VPN IP address
Endpoint Client's real IP address and port
Handshake Last handshake timestamp
Transfer RX/TX Bytes received / sent
Bandwidth Configured bandwidth limit
Server Network name

Client Profiles Tab

WireGuard client profiles WireGuard client profiles — all clients across all networks

Lists all WireGuard clients across all networks:

Column Description
Client Name Client name (link to client page)
Username System user who owns this client
Network Network this client belongs to
Status Enable/Disable
Keys Key status (Active = keys generated)

Each client row has buttons to edit the client and download the WireGuard configuration file.

Client Configuration

Each client automatically gets:

Supported client platforms:

How It Works

Client App                    PUQVPNCP Server
----------                    ---------------
[WireGuard]  ---- UDP ----->  [wg51823 interface]
                                    |
                              iptables mangle (mark)
                                    |
                              policy routing (table)
                                    |
                              +-------------+
                              |  Upstream   |
                              | (direct or  |
                              |  wgupN)     |
                              +-------------+
                                    |
                              SNAT + forward
                                    |
                                Internet
  1. Client connects to the WireGuard UDP port
  2. Packets arrive on the network's WireGuard interface (e.g., wg51823)
  3. iptables mangle rules mark the traffic for policy routing
  4. Traffic is routed through the configured upstream (direct internet or WireGuard tunnel)
  5. SNAT is applied for internet access

08. IKEv2

Overview

IKEv2/IPsec is a standards-based VPN protocol with native support in most operating systems. PUQVPNCP uses strongSwan as the IKEv2 implementation.

Key advantages:

IKEv2 is the best choice when you want zero-install VPN for end users — they can configure it using only the native OS settings.

Requirement: strongswan and strongswan-pki packages must be installed.

Global Settings

Navigate to VPN Servers > IKEv2 to configure global IKEv2 settings.

IKEv2 settings IKEv2 global settings

Setting Description
Enabled Enable/disable IKEv2 globally
Ports 500 / 4500 UDP (standard IPsec ports)

Advanced Settings

IKEv2 advanced IKEv2 advanced settings

Setting Description Default
ESP ESP encryption proposals aes256gcm128-sha256
IKE IKE encryption proposals aes256-sha256-modp2048
IKE Lifetime (sec) IKE SA lifetime 86400
Lifetime (sec) Child SA lifetime 3600
DPD Delay Dead Peer Detection interval 30
DPD Timeout DPD timeout 150

Certificates

IKEv2 uses X.509 certificates for server authentication. PUQVPNCP manages the full PKI chain.

Root Certificate (CA)

Root certificate IKEv2 Root CA certificate

The Root CA is created once and signs all server certificates. Clients must trust this CA.

Server Certificate

Server certificate IKEv2 server certificate

The server certificate is signed by the Root CA and presented to clients during the IKE handshake.

Important: The server certificate's Subject Alternative Name (SAN) must match the VPN Domain or server IP.

Import Certificate

Import certificate Import existing CA and server certificates

If you have existing certificates from another strongSwan installation, you can import them instead of generating new ones.

DNS

IKEv2 DNS IKEv2 DNS configuration

Configure DNS servers pushed to IKEv2 clients.

Status

IKEv2 status IKEv2 service status

Shows the strongSwan daemon status, starter and charon PIDs, and current active SAs.

Online Users

IKEv2 online IKEv2 online users

Lists all active IKEv2 security associations with:

Client Profiles

IKEv2 client profiles IKEv2 client profiles — all clients across all networks

Lists all IKEv2 clients across all networks:

Column Description
Client Name Client name (link to client page)
Username System user who owns this client
Network Network this client belongs to
Status Enable/Disable

Each client row has buttons to edit the client and download the .sswan configuration file.

Client Configuration

IKEv2 clients authenticate using username/password (EAP-MSCHAPv2) with server certificate validation.

Configuration by Platform

Platform Method
iOS Settings > VPN > Add Configuration > IKEv2. Or import .mobileconfig profile
macOS System Preferences > Network > + > VPN > IKEv2
Windows Settings > Network > VPN > Add VPN > IKEv2
Android Settings > VPN > + > IKEv2/IPsec MSCHAPv2 (or use strongSwan app)
Linux NetworkManager or charon-cmd

Required Client Settings

Field Value
Server Your VPN domain or IP
Remote ID Same as server (domain or IP)
Authentication Username (EAP)
Username / Password From client's IKEv2 tab
CA Certificate The Root CA certificate (download from panel)

Tip: Use One-Time Links to give users a downloadable .sswan profile that imports all settings automatically.

Per-Network Configuration

Each network can override the global IKEv2 settings:

See the IKEv2 tab in Networks for details.

09. OpenVPN

Overview

OpenVPN is a mature, widely-supported VPN protocol based on SSL/TLS. PUQVPNCP manages OpenVPN with full PKI (Easy-RSA) integration.

Key advantages:

OpenVPN is the best choice when you need maximum compatibility or when clients are behind restrictive firewalls that block WireGuard and IKEv2 traffic.

Requirement: openvpn and easy-rsa packages must be installed.

Navigate to VPN Servers > OpenVPN to access OpenVPN management. The page has 6 tabs: Overview, Certificates, Settings, Networks, Online, Client Profiles.

Overview Tab

OpenVPN overview OpenVPN overview — service status, certificates, configuration, online connections

The Overview tab shows:

Card Description
Service Status Installed openvpn and easy-rsa package versions
Certificate Status Status of CA, Server Certificate, DH Parameters, and TLS Auth Key (Valid/Missing)
Configuration OpenVPN enabled/disabled, number of networks and clients
Online Connections Number of currently active OpenVPN connections with a link to view all

Certificates Tab

Before OpenVPN can be enabled, you must generate all required certificates. The Certificates tab guides you through the PKI setup step by step.

Step 1: Generate CA Certificate

Certificates — initial setup Certificates tab — initial state, CA certificate form

Fill in the CA Certificate fields:

Field Description Example
Common Name CA certificate name myserver.com CA
Organization Organization name myserver.com
Organizational Unit (optional) Department
Locality (optional) City
State / Province (optional) State
Country (optional) Country code

Click Generate CA Certificate to create the root CA.

Step 2: Generate Server Certificate and DH Parameters

Certificates — CA generated Certificates tab — CA generated, generating server certificate

After the CA is generated:

  1. Click Generate Server Certificate — creates the server's TLS certificate signed by the CA
  2. Click Generate DH Parameters — creates Diffie-Hellman parameters (takes ~1 minute)

Certificates — DH generating Certificates tab — DH parameters generating

Step 3: Generate TLS Auth Key

Certificates — generating TLS Auth Certificates tab — generating TLS Auth key

Click Generate TLS Auth Key to create the HMAC authentication key.

Step 4: All Certificates Ready

Certificates — all generated Certificates tab — all certificates and keys generated

Certificates — complete with details Certificates tab — all valid, certificate details panel

Once all 4 components are generated (CA, Server, DH, TLS Auth), you can enable OpenVPN:

Certificates — OpenVPN enabled Certificates tab — OpenVPN enabled

Set OpenVPN Enabled to YES and save. The right panel shows the CA certificate details (issuer, validity dates, fingerprint).

Settings Tab

OpenVPN settings OpenVPN settings — connection and performance defaults

Configure global defaults for OpenVPN. These settings are applied to all networks unless overridden at the network level.

Connection

Setting Description Default
Protocol UDP or TCP udp
Cipher Encryption cipher AES-256-GCM
Auth Digest HMAC authentication digest SHA256
TLS Cipher TLS cipher suite (optional) (empty)
Compression lz4-v2, lzo, or disabled lz4-v2
Port Start Starting port for network instances 1194
Client-to-Client Allow clients to communicate directly NO
Duplicate CN Allow multiple connections with same certificate NO
Persist Key Keep keys across restarts YES
Persist Tun Keep tunnel device across restarts YES

Performance & Limits

Setting Description Default
Keepalive (sec) Ping interval 10
Keepalive Timeout (sec) Connection timeout 120
Max Clients Maximum simultaneous clients per instance 100
Verbosity Log verbosity level (0-11) 3
MTU (tun-mtu) Tunnel MTU 1420
MSS Fix Clamp MSS to avoid fragmentation (0 = disabled) 0
Fragment Fragmentation size (0 = disabled) 0

Use the Restore defaults button to reset all settings to their original values.

Networks Tab

OpenVPN networks OpenVPN networks — list of all OpenVPN instances

Shows all networks that have OpenVPN enabled:

Column Description
Name Network name (link to network edit page)
Clients Number of OpenVPN clients in this network
Port UDP/TCP port for this network's OpenVPN instance
Proto Protocol (udp/tcp)
Network Subnet assigned to this network
Bandwidth Upload / download bandwidth limits

Online Tab

OpenVPN online OpenVPN online users — currently connected clients

Shows all active OpenVPN sessions:

Column Description
Name Client name (link to client page)
Username System user who owns this client
Virtual IP IP assigned inside the VPN tunnel
Real IP Client's real IP address and port
Bytes RX Bytes received from client
Bytes TX Bytes sent to client
Connected Since Connection start timestamp
Network Network name

Each row has buttons to edit the client or disconnect the session.

Client Profiles Tab

OpenVPN client profiles OpenVPN client profiles — all clients across all networks

Lists all OpenVPN clients across all networks:

Column Description
Client Name Client name (link to client page)
Username System user who owns this client
Network Network this client belongs to
Status Enable/Disable
Certificate Certificate status (Issued/Missing)

Each client row has buttons to edit the client and download the .ovpn configuration file.

Client Configuration

Each OpenVPN client automatically gets:

The .ovpn profile contains everything needed to connect:

Supported Client Apps

Platform App
Windows OpenVPN GUI, OpenVPN Connect
macOS Tunnelblick, OpenVPN Connect
Linux openvpn CLI, NetworkManager
Android OpenVPN Connect (Play Store)
iOS OpenVPN Connect (App Store)
Mikrotik RouterOS 7+ OVPN client

Per-Network Configuration

Each network has its own OpenVPN instance with:

See the OpenVPN tab in Networks for details.

10. Upstreams (WireGuard Tunnels)

Overview

Upstreams allow you to route VPN client traffic through external WireGuard VPN servers instead of the PUQVPNCP server's own internet connection. This creates a multi-hop VPN chain:

VPN Client ---> PUQVPNCP Server ---> WireGuard Upstream ---> Internet
                                       (wgupN)

Each upstream is a WireGuard tunnel to a remote VPN server. Networks can be individually assigned to different upstreams, giving you full control over which exit IP each group of clients uses.

Why Use Upstreams?

1. Geographic IP Rotation

Assign different networks to upstreams in different countries. Clients on "Network US" exit through a US server, clients on "Network EU" exit through a European server — all managed from a single PUQVPNCP instance.

                         +-- wgup0 (US server)  ---> US IP
                         |
Client ---> PUQVPNCP -----+-- wgup1 (EU server)  ---> EU IP
                         |
                         +-- direct (ens18)      ---> Server IP

2. Multi-Hop Privacy

Add an extra encryption layer between your server and the internet. Even if someone monitors your server's traffic, they see encrypted WireGuard traffic to the upstream, not the client's actual browsing.

3. ISP / IP Reputation Bypass

When your server's IP is blocked or blacklisted (e.g., by streaming services), route traffic through a clean upstream IP without migrating your entire infrastructure.

4. Dedicated Exit Nodes for Tenants

In a multi-tenant setup, give each customer their own exit IP:

Network Upstream Exit IP Customer
corp_acme wgup0 (Frankfurt) 185.x.x.1 Acme Corp
corp_globex wgup1 (London) 51.x.x.2 Globex Inc
internal direct (ens18) 77.x.x.200 Internal

5. Load Distribution

Spread bandwidth across multiple upstream tunnels to avoid congestion on a single exit point.

6. Failover Planning

If your primary upstream goes down, simply reassign the network to a backup upstream. Client configurations don't change — only the server-side routing updates.

Upstreams Page

Navigate to VPN Servers > Upstreams to manage system and WireGuard upstreams.

Upstreams list Upstreams page — System upstreams (server IPs) and WireGuard upstreams

System Upstreams

The top section shows all server IP addresses available as direct internet exits:

Field Description
IP Server IP address
Interface Network interface (e.g., ens18, ens18:1)
Status UP / DOWN
Primary Whether this IP is marked as primary

WireGuard Upstreams

The bottom section shows configured WireGuard tunnels:

Field Description
Name Upstream identifier
Endpoint Remote WireGuard server address:port
Address Local tunnel IP (assigned by remote server)
Interface Auto-generated interface name (wgup0, wgup1, ...)
Status connected / disconnected
Handshake Time since last successful handshake
RX / TX Traffic through the tunnel

Creating an Upstream

Click the + button to add a new WireGuard upstream.

Edit upstream Edit WireGuard upstream configuration

Field Description
Name Unique name for this upstream
Description Optional description
Endpoint Remote server address and port (e.g., vpn.example.com:51820)
Tunnel Address Your local IP in the tunnel (e.g., 172.16.1.2/24)
DNS Optional DNS through the tunnel
Private Key Your WireGuard private key. Click Generate to create a new key pair.
Public Key (remote server) The remote server's public key
Preshared Key Optional pre-shared key for extra security
Allowed IPs Which traffic to route through the tunnel (usually 0.0.0.0/0)
MTU Tunnel MTU (default: 1340 for double-encapsulation)
Keepalive Persistent keepalive interval (default: 25)
Enabled (auto-connect) Automatically connect on service start

Importing a WireGuard Config

Click the Import button to paste an existing WireGuard .conf file.

Import config Import WireGuard configuration from a .conf file

Paste the content of a standard WireGuard configuration file:

[Interface]
PrivateKey = ...
Address = 172.16.1.2/24

[Peer]
PublicKey = ...
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0

The parser automatically extracts all fields and creates the upstream.

Assigning an Upstream to a Network

After creating an upstream, assign it to any network:

  1. Go to Networks > Edit your network
  2. In the Upstream dropdown, select the WireGuard upstream
  3. Click Save and Reload

The network's traffic will now be routed through the selected upstream tunnel.

Network upstream selector Network edit — Upstream field showing a WireGuard upstream selection

How It Works Internally

When a network uses a WireGuard upstream:

1. Client traffic arrives on VPN interface (wg51823, ovpn1197, etc.)
2. iptables mangle marks traffic with CONNMARK
3. Policy routing (ip rule + ip route) directs marked traffic to wgupN
4. SNAT replaces the source IP with the upstream tunnel IP
5. Traffic exits through the WireGuard upstream to the internet
6. Return traffic follows the same path back to the client

Routing Chain

VPN Client (10.0.0.2)
    |
    ▼
WireGuard/OpenVPN/IKEv2 interface
    |
    ▼
iptables CONNMARK (set mark on wg/ovpn interface)
    |
    ▼
ip rule: fwmark → lookup table N
    |
    ▼
ip route: default via wgupN (in table N)
    |
    ▼
iptables SNAT: source → tunnel IP (172.16.1.2)
    |
    ▼
WireGuard upstream tunnel (wgupN)
    |
    ▼
Remote VPN server → Internet

Note: The upstream tunnel uses a reduced MTU (1340 by default) to accommodate double encapsulation.

Practical Setup Example

Scenario: Route office network through a US VPN server

Step 1: Get a WireGuard VPN account from a US provider (e.g., Mullvad, ProtonVPN, or your own server).

Step 2: In PUQVPNCP, go to VPN Servers > Upstreams, click Import, paste the .conf file.

Step 3: Connect the upstream (click the Play button).

Step 4: Verify the upstream is connected (Status: connected, Handshake: recent).

Step 5: Go to Networks, edit your office network, select the new upstream in the Upstream dropdown.

Step 6: Save and Reload. All clients on that network now exit through the US IP.

Troubleshooting

Issue Solution
Upstream shows disconnected Check endpoint address, keys, and firewall on both sides
No handshake Verify the remote server's public key and that UDP port is open
Clients have no internet Check that Allowed IPs is 0.0.0.0/0 and SNAT is working
Slow speeds Reduce MTU, check upstream bandwidth, ensure keepalive is set

11. Network Peering

Overview

Network Peering allows VPN clients from different networks to communicate with each other. By default, networks are isolated — clients in Network A cannot reach clients in Network B. Peering rules create explicit exceptions.

Peering List

Navigate to Networks > Peering.

Peering list Network peering rules

Column Description
Name Rule identifier
Network A First network
Network B Second network
Bidirectional Whether traffic flows both ways

Adding a Peering Rule

Click the + button to create a new peering rule.

Add peering Add a new peering rule

Field Description
Name Rule name
Network A First network
Network B Second network
Bidirectional If enabled, both networks can reach each other. If disabled, only A can reach B.

After adding a rule, the panel shows a warning to apply the firewall.

Peering changed Peering rules updated — 3 rules configured

Click Apply Firewall to activate the new rules.

Peering apply warning Warning: Peering rules changed, click Apply Firewall to apply

Peering applying Applying firewall rules with countdown

Use Cases

Office-to-Office Communication

Connect clients from two office networks:

Server Access from VPN

Allow VPN clients to access a management network:

IoT Monitoring

Allow monitoring network to reach IoT devices:

How It Works

Peering rules create iptables FORWARD rules that allow traffic between the specified network subnets. Without peering, the default auto_isolation_ipset rule in Pre-Network Rules drops inter-network traffic.

12. Firewall

Overview

PUQVPNCP manages the Linux firewall (iptables / ip6tables) with two layers:

  1. Global firewall — server-wide policies, Pre-Network and Post-Network custom rules, ipset
  2. Per-network firewall — auto-generated filter, NAT, DNAT, and mangle rules per network

Global Firewall

Navigate to Settings > Firewall.

Settings Tab

Firewall settings Firewall settings — global policies

Setting Description Recommended
Forwarding (NAT) Enable SNAT for VPN clients Enabled
INPUT policy Default for incoming traffic ACCEPT
FORWARD policy Default for forwarded traffic ACCEPT
OUTPUT policy Default for outgoing traffic ACCEPT

Pre-Network Rules

Pre-network rules Pre-Network rules — executed before per-network rules

Pre-Network rules are applied before any per-network rules. Use them for:

Add pre-network rule Adding a custom pre-network rule

Field Description
Name Rule identifier
Chain INPUT, FORWARD, or OUTPUT
Action ACCEPT, DROP, REJECT, LOG
Protocol TCP, UDP, ICMP, or ANY
Source IP / Dest IP IP addresses or CIDR ranges
Source Port / Dest Port Port numbers (0 = any)

After adding rules, click Apply Firewall to activate.

Rules changed Rules modified — warning to apply

Applying Applying firewall rules

Post-Network Rules

Post-network rules Post-Network rules — executed after per-network rules

Same format as Pre-Network rules, but applied after per-network rules.

ipset Tab

ipset ipset — VPN network subnets for global isolation

The puq_vpn_nets ipset contains all VPN network subnets and is used by the auto_isolation_ipset rule to prevent inter-network traffic (unless Peering rules allow it).

Per-Network Firewall

Each network has its own firewall tab with auto-generated rules.

Network firewall Per-network firewall — Filter, NAT, DNAT rules

Rule Types

Type Description
Filter Rules Traffic logging (auto_log_out/in) and custom filter rules
NAT Rules SNAT for internet access (auto_nat_NETWORK → upstream IP)
DNAT Rules Port forwarding rules (from Port Forwarding tab)
Mangle Rules Traffic marking for TC bandwidth control and policy routing

Mangle rules Mangle rules — per-client traffic marks and CONNMARK for policy routing

Mangle rules are fully auto-generated:

Rule Execution Order

1. Pre-Network Rules    (global, custom)
2. Per-Network Rules    (auto-generated per network)
   +-- Filter Rules     (logging, custom filters)
   +-- NAT Rules        (SNAT for upstream)
   +-- DNAT Rules       (port forwarding)
   +-- Mangle Rules     (TC marks, CONNMARK)
3. Post-Network Rules   (global, custom)
4. Global Policies      (INPUT/FORWARD/OUTPUT defaults)

13. DNS

Overview

PUQVPNCP includes a built-in bind9 DNS server that provides DNS resolution for all VPN clients. The DNS page is organized into three tabs: Settings, Records, and Ad Blocking.

Requirement: bind9 and bind9-utils packages must be installed.

Settings

The Settings tab controls the bind9 DNS server configuration.

DNS Settings DNS Settings tab — server configuration and ACL

Setting Description
Enabled Enable or disable the bind9 DNS server
Forwarder DNS 1 Primary upstream DNS server for recursive queries
Forwarder DNS 2 Secondary upstream DNS server
Max Cache TTL Maximum time (30–3600 seconds) DNS responses are cached

The ACL section at the bottom displays all IP addresses and subnets that are allowed to query this DNS server. This list is automatically generated from your VPN network configurations — it includes localhost, server IPs, and all VPN network subnets.

Tip: Set the network's DNS 1 to the VPN gateway IP (e.g., 10.0.0.1) so clients use this built-in resolver. This prevents DNS leaks and enables ad blocking.

Click the checkmark button in the top right to save changes.

Records

The Records tab manages custom DNS entries using bind9 Response Policy Zone (RPZ). These records override public DNS for all VPN clients.

DNS Records DNS Records tab — RPZ overrides for VPN clients

Column Description
Domain Full domain name (e.g., puqcloud.com, internal.vpn)
Type Record type — A (IPv4), AAAA (IPv6), CNAME, etc.
Value Target IP address or hostname

Click the + button to add a new record. Each record can be edited or deleted using the action buttons on the right.

Use cases:

Ad Blocking

The Ad Blocking tab provides DNS-level ad and tracker blocking for all VPN clients. No client-side software is needed — it works automatically for any device connected to the VPN.

DNS Ad Blocking Ad Blocking tab — enable/disable, block lists, whitelist

How It Works

When a VPN client requests a domain that is on a block list (e.g., ads.google.com), the DNS server responds with NXDOMAIN (domain does not exist) instead of the real IP address. This prevents ads, trackers, and malware from loading across all apps and browsers.

Ad blocking uses a separate RPZ zone (rpz.adblock) that is independent of your static DNS records in the Records tab.

Configuration

Setting Description
Ad Blocking Enable or disable ad blocking (YES/NO)
Total Blocked Number of unique domains currently blocked
Last Update Timestamp of the last block list update

Block Lists

PUQVPNCP ships with 4 built-in block lists that cover ads, trackers, and malware domains:

List Description Domains
Steven Black Unified Ads, malware, fakenews — most popular community list ~82,000
OISD Small Curated list with minimal false positives ~51,000
Pete Lowe Only verified ad servers — very conservative ~3,500
Hagezi Multi Pro Comprehensive, actively maintained ~183,000

Built-in lists are marked with a builtin badge. They cannot be deleted but can be toggled on/off using the checkbox.

With all lists enabled, approximately 320,000 unique domains are blocked (after deduplication).

Supported blocklist formats:

Custom Lists

Click the + button in the Block Lists card to add a custom blocklist URL:

Field Description
Name Display name for the list
URL HTTP/HTTPS URL to the blocklist file
Enabled Whether the list is active

Custom lists can be deleted; built-in lists cannot.

Whitelist

The Whitelist section allows you to exclude specific domains from blocking. When a domain is whitelisted, it and all its subdomains are excluded from ad blocking.

For example, whitelisting example.com will also unblock sub.example.com, api.example.com, etc.

Click the + button in the Whitelist card to add a domain.

Auto-Update

Block lists are automatically refreshed every 24 hours. The Last Update timestamp and per-list domain counts are shown on the Ad Blocking tab.

To force an immediate update, click Update Now. This downloads all enabled lists, deduplicates domains, applies the whitelist, and reloads bind9.

API

DNS and ad blocking can be fully managed via the REST API:

Method Endpoint Description
GET /api/v1/dns Get DNS configuration
PUT /api/v1/dns Update DNS settings
GET /api/v1/dns/adblock Get ad blocking configuration and statistics
PUT /api/v1/dns/adblock Enable/disable ad blocking, toggle lists
POST /api/v1/dns/adblock/update Force update block lists
POST /api/v1/dns/adblock/lists Add custom block list
DELETE /api/v1/dns/adblock/lists/{name} Delete custom list
GET /api/v1/dns/adblock/whitelist List whitelisted domains
POST /api/v1/dns/adblock/whitelist Add domain to whitelist
DELETE /api/v1/dns/adblock/whitelist/{name} Remove domain from whitelist

See API Reference for full endpoint documentation with request/response examples.

14. One-Time Links

Overview

OTL Configuration

Navigate to Settings > One-time link.

Setting Description
Enabled Enable/disable the OTL feature
Expiration How long a link remains valid
Max uses Number of times a link can be accessed (0 = unlimited)

Protocol-Specific Configuration

Configure what is shown on the OTL page for each protocol:

WireGuard OTL config OTL WireGuard page configuration

AmneziaWG OTL config OTL AmneziaWG page configuration

IKEv2 OTL config OTL IKEv2 page configuration

OpenVPN OTL config OTL OpenVPN page configuration

The list shows all generated links with their creation date, client, and usage count.

From the Clients List

  1. Go to Clients > List of clients
  2. Click the OTL button on any client row

From the Client Edit Page

  1. Open any client for editing
  2. In the One-Time Link section, click Create

Copy the URL and send it to the end user. They will see a branded page with their VPN configuration for all enabled protocols.

End User Experience

When the user opens the OTL URL, they see a clean, modern self-service interface with tabs for each enabled VPN protocol. The user can download client apps, configurations, credentials, and scan mobile QR codes.

WireGuard

AmneziaWG (Anti-Censorship)

OpenVPN

IKEv2

15. Monitoring

Overview

PUQVPNCP provides comprehensive traffic monitoring:

Configuration

Navigate to Settings > Monitoring.

Traffic Logging

Monitoring config Monitoring configuration — traffic logging

Setting Description
Logging Enable iptables traffic logging via rsyslog
Log format Log format template

Remote Syslog

Remote syslog Remote syslog configuration

Forward traffic logs to a remote syslog server for centralized logging.

InfluxDB

InfluxDB config InfluxDB configuration

Setting Description
Enabled Enable InfluxDB export
URL InfluxDB server URL (e.g., https://idb01.example.com)
Token Authentication token
Organization InfluxDB organization
Bucket Target bucket

Metrics Endpoint

Metrics config Metrics endpoint configuration

Enable a Prometheus-compatible HTTP metrics endpoint at http://127.0.0.1:8098/metrics.

Monitoring Status

Monitoring status Monitoring services status

Shows the current state of all monitoring components:

After changing monitoring settings and clicking Save, the configuration is applied with a countdown:

Monitoring applying Applying monitoring configuration

Grafana Integration

Connect Grafana to your InfluxDB instance to create custom VPN dashboards.

Grafana dashboard Example Grafana dashboard with VPN traffic metrics

Available Metrics

Metric Description
client_download_bytes Per-client download traffic
client_upload_bytes Per-client upload traffic
network_download_bytes Per-network download traffic
network_upload_bytes Per-network upload traffic
online_wireguard WireGuard online peer count
online_openvpn OpenVPN connected session count
online_ikev2 IKEv2 active SA count

16. Backups

Overview

PUQVPNCP provides automatic and manual backup/restore functionality with optional FTP upload for offsite storage.

Backup List

Navigate to Settings > Backups.

Backups list Backup list with create, restore, download, and delete actions

Each backup includes:

Actions

Action Description
Create Create a new backup immediately
Restore Restore the server to the backup state
Download Download the backup archive
Delete Delete the backup file
Upload Upload a backup file

Backup Configuration

Backup config Backup scheduler configuration

Automatic Backups

Setting Description
Hourly Enable/disable hourly backups
Daily Enable/disable daily backups
Daily time Time for daily backup (e.g., 14:45)
Max backups Maximum number of backups to keep (oldest are deleted)

FTP Backup

Setting Description
FTP Backup Enable/disable FTP upload after each backup
FTP Server FTP server address
FTP Port FTP port (default: 21)
FTP Username FTP login
FTP Password FTP password
FTP Directory Remote directory for backups

Tip: Use Test FTP button to verify the FTP connection before enabling automatic uploads.

Restoring a Backup

  1. Go to Settings > Backups
  2. Click Restore on the desired backup
  3. Confirm the restore operation
  4. The system will reload automatically after restoration

Warning: Restoring a backup overwrites all current configurations and data. Create a backup of the current state before restoring.

17. System Settings

System Users

Navigate to Settings > System users.

Users list System users list

PUQVPNCP supports multiple administrator accounts with role-based access control.

Adding a User

Add user Add a new system user

Field Description
Username Unique login name
Email User email
Password Account password
Groups Permission groups assigned to this user

Editing a User

Edit user Edit system user

Permission Groups

Navigate to Settings > Permission groups.

Groups list Permission groups list

Permission groups define what actions a user can perform. PUQVPNCP includes 36+ granular permissions across 17 resource categories.

Default Groups

Group Access Level
admin Full access to everything
operator All operations except system settings
viewer Read-only access to all pages

Creating a Custom Group

Add group Create a new permission group

Edit group Edit permission group — select permissions by resource

Permissions are organized by resource:

Resource Permissions
system_config read, write
wireguard read, write
amneziawg read, write
network read, write
client read, write
peering read, write
account read, write
openvpn read, write
ikev2 read, write
diagnostics read, write
firewall read, write
dns read, write
otl read, write
traffic (Monitoring) read, write
backups read, write
license read, write
api_tokens read, write
system_users read, write
permission_groups read, write

API Tokens

Navigate to Settings > API Tokens.

Tokens list API tokens list

API tokens provide programmatic access to the REST API without using session cookies.

Creating a Token

Create token Create a new API token

Field Description
Name Token description
Username The user this token belongs to (inherits permissions)
Allowed IP Restrict token to a specific IP (empty = any)
Expires At Token expiration date (empty = never)

Token created Token created — copy the token now, it won't be shown again

Important: The token value is shown only once. Copy it immediately after creation.

Usage

Include the token in the Authorization header:

curl -sk https://vpn.example.com/api/v1/system/status \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Environment Check

Navigate to Settings > Environment.

Environment check Environment check — verify all required packages

The Environment page scans for all required and optional system packages:

Environment bottom Environment check — DNS, Monitoring, Security, System Utilities

Environment networking Environment check — Network Configuration (ifupdown2 / netplan.io)

Missing packages are highlighted and can be installed via the system package manager.

About Us & Project Support

Navigate to About us in the top navigation bar.

About Us and Support About Us — licensing information, WHMCS provisioning module integration, and support links

The About page displays project license limits (up to 50 VPN clients without license, unlimited with license from puqcloud.com), integration options including the official PUQVPNCP WHMCS Provisioning Module, and links to documentation and support.

18. REST API

Overview

PUQVPNCP provides a comprehensive REST API with 240+ endpoints covering all panel functionality. The API uses JSON for requests and responses.

Authentication

All API endpoints require authentication via Bearer token:

curl -sk https://vpn.example.com/api/v1/system/status \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Create API tokens in Settings > API Tokens. See System Settings for details.

Base URL

https://your-server.com/api/v1/

OpenAPI / Swagger Documentation

PUQVPNCP includes built-in interactive API documentation.

Swagger UI

Navigate to the API page in the web interface to access Swagger UI.

Swagger UI Swagger UI — interactive API documentation

Swagger endpoints Swagger UI — endpoint groups

OpenAPI Spec

The OpenAPI 3.0 JSON specification is available at:

https://your-server.com/api/v1/openapi.json

This endpoint does not require authentication and can be imported into Postman, Insomnia, or any OpenAPI-compatible tool.

API Endpoint Groups

Group Endpoints Description
System 8 Status, info, reload, config, environment
Networks 11 CRUD + suggested data + keys regeneration
Clients 17 CRUD + online clients + config/QR per protocol
Peering 3 CRUD for peering rules
WireGuard 17 Server config + settings + keys + clients list
AmneziaWG 18 Server config, settings, client keys & profiles, obfuscation parameters, magic headers, QR codes
OpenVPN 12 Server config + clients list
IKEv2 13 Server config + clients list
Upstreams 10 CRUD + connect/disconnect + import
Firewall 12 Settings + pre/post rules CRUD
DNS 2 Config GET/PUT
One-Time Links 12 Config + links CRUD per protocol
Monitoring 4 Config, status, metrics
Backups 9 List, create, restore, config, FTP
License 3 Save, delete, check
API Tokens 4 CRUD
Permission Groups 5 CRUD + registry
System Users 6 CRUD + profile
Diagnostics 5 Protocol logs (WG, AWG, OpenVPN, IKEv2, firewall, system), info, TC stats

Response Format

Success Response

{
  "result": "OK",
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response

{
  "result": "ERROR",
  "message": "Descriptive error message",
  "errors": {
    "field_name": "Validation error for this field"
  }
}

Common API Examples

Get System Status

curl -sk https://vpn.example.com/api/v1/system/status \
  -H "Authorization: Bearer TOKEN"

List All Networks

curl -sk https://vpn.example.com/api/v1/network \
  -H "Authorization: Bearer TOKEN"

Create a Client

curl -sk -X POST https://vpn.example.com/api/v1/client \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new_client",
    "username": "user1",
    "password": "SecurePass123",
    "network": "office_vpn",
    "status": "Enable",
    "bandwidth_download": 10,
    "bandwidth_upload": 5
  }'

Get Client WireGuard Config

curl -sk https://vpn.example.com/api/v1/client/new_client/wireguard \
  -H "Authorization: Bearer TOKEN"

Get Client AmneziaWG Config

curl -sk https://vpn.example.com/api/v1/client/new_client/amneziawg/config \
  -H "Authorization: Bearer TOKEN"

Reload System

curl -sk -X POST https://vpn.example.com/api/v1/system/reload \
  -H "Authorization: Bearer TOKEN"

Integration

The API enables integration with:

19. Use Cases

1. VPN Service Provider

Goal: Sell VPN subscriptions to end users with different speed tiers.

Setup

Network Subnet Bandwidth Upstream
basic 10.100.1.0/24 10/5 Mbit Direct (server IP)
premium 10.100.2.0/24 100/50 Mbit Direct (server IP)
business 10.100.3.0/24 Unlimited WireGuard upstream (dedicated IP)

How It Works

  1. Create networks with different bandwidth limits
  2. Use the official PUQVPNCP WHMCS Provisioning Module or custom REST API integration to automate client sales and provisioning
  3. Send One-Time Links to customers so they can self-configure their devices
  4. Monitor traffic via InfluxDB + Grafana dashboards

Key Features Used

2. Multi-Country VPN with Upstream Tunnels

Goal: Offer VPN exits in multiple countries from a single server.

Setup

PUQVPNCP Server (Frankfurt)
+-- Network "exit_us"   ---> Upstream wgup0 (New York)    ---> US IP
+-- Network "exit_uk"   ---> Upstream wgup1 (London)      ---> UK IP
+-- Network "exit_jp"   ---> Upstream wgup2 (Tokyo)       ---> JP IP
+-- Network "exit_de"   ---> Direct (ens18)               ---> DE IP

How It Works

  1. Rent cheap WireGuard VPN servers in target countries
  2. Add them as Upstreams in PUQVPNCP (import their .conf files)
  3. Create a network per country, assign each to its upstream
  4. Clients choose their exit country by connecting to the appropriate network
  5. One-Time Links can be generated per-network for easy distribution

Key Features Used

3. Corporate Remote Access

Goal: Provide secure remote access for employees to internal company resources.

Setup

Network Subnet Purpose
employees 10.0.1.0/24 General employees — access email, intranet
developers 10.0.2.0/24 Developers — access staging servers
admins 10.0.3.0/24 IT admins — full infrastructure access

Network Peering

Rule Network A Network B Direction
dev_to_staging developers staging_net Bidirectional
admin_full admins all_servers Bidirectional

How It Works

  1. Create separate networks per department with different access levels
  2. Use Network Peering to control which departments can access which resources
  3. Use Custom Routes to push only necessary subnets (split tunnel)
  4. IKEv2 is ideal here — native on all employee devices, no app to install
  5. Permission Groups allow the IT team to manage VPN without full admin access

Key Features Used

4. IoT Device Management

Goal: Securely connect remote IoT devices (cameras, sensors, POS terminals) back to a central network.

Setup

Network Subnet Client-to-Client Upstream
iot_cameras 10.10.1.0/24 No Direct
iot_sensors 10.10.2.0/24 No Direct
monitoring 10.10.3.0/24 Yes Direct

How It Works

  1. Each IoT device gets a WireGuard client with a static IP
  2. Client-to-Client is disabled — devices cannot communicate with each other
  3. The monitoring network peers with IoT networks for centralized monitoring
  4. Port Forwarding rules expose specific device ports to the server's public IP
  5. Bandwidth limits prevent devices from saturating the connection

Key Features Used

5. Hosting Provider — VPN as a Service

Goal: Offer managed VPN accounts to hosting customers, integrated with billing.

Architecture

WHMCS / Billing ---> PUQVPNCP API ---> VPN Networks
                                          |
                    +---------------------+
                    |                     |
              Customer A              Customer B
              Network: acme_co        Network: globex_inc
              Clients: 50             Clients: 200
              Upstream: dedicated     Upstream: shared

How It Works

  1. Each customer gets a dedicated network with their own subnet
  2. Use the official PUQVPNCP WHMCS Provisioning Module or direct REST API calls to:
    • Create networks when a customer signs up
    • Add/remove clients based on subscription
    • Suspend clients on non-payment
    • Delete everything on cancellation
  3. Customers receive One-Time Links for self-setup or download profiles directly from their WHMCS client area
  4. API Tokens per customer allow limited self-management

Turnkey WHMCS Integration

With the PUQVPNCP WHMCS Module, this entire workflow is 100% automated out of the box — including client account provisioning, suspension, quota enforcement, and config delivery (WireGuard, AmneziaWG, OpenVPN, IKEv2).

Key Features Used

6. Privacy-Focused Multi-Hop VPN

Goal: Maximum privacy with double encryption and IP masking.

Setup

User ---> PUQVPNCP (Entry Server) ---> Upstream wgup0 (Exit Server) ---> Internet
         WireGuard encrypted            WireGuard encrypted
         User sees Entry IP             Sites see Exit IP

How It Works

  1. PUQVPNCP acts as the entry node — users connect here
  2. All traffic is forwarded through a WireGuard upstream tunnel to an exit node
  3. The exit node has no knowledge of the original user's IP
  4. Even if the entry server is compromised, traffic is encrypted to the exit
  5. Different networks can use different exit nodes for variety

Key Features Used

7. Small Office / Home Office (SOHO)

Goal: Simple VPN for a small team (5-20 people) with shared file access.

Setup

Network Subnet Protocols Special
office 10.0.0.0/24 WG + IKEv2 Client-to-Client: Yes

How It Works

  1. Single network with client-to-client enabled
  2. Team members connect via IKEv2 (no app needed) or WireGuard (better speed)
  3. File sharing works directly between connected devices
  4. One-Time Links sent to each team member for easy setup
  5. The admin manages everything via the web panel with 2-3 permission groups

Key Features Used

8. Anti-Censorship & DPI Bypass (AmneziaWG)

Goal: Bypass strict government or ISP Deep Packet Inspection (DPI) censorship systems that block standard WireGuard or OpenVPN protocols.

Setup

  1. Enable AmneziaWG in the network settings
  2. Configure custom obfuscation parameters:
    • H1–H4 random packet headers
    • Jc (3–5 junk packets) with sizes Jmin (40) and Jmax (70)
    • S1 (15) and S2 (20) initiation and response junk
  3. Generate One-Time Links for clients
  4. Users scan the QR code or import .conf into official AmneziaWG client apps (Android, iOS, Windows, macOS)

Key Features Used

Protocol Selection Guide

20. Troubleshooting

Reset Admin Password

If you have lost access to the web panel or forgotten the admin password, you can reset it using the recovery mode.

Step 1: Stop the Service

systemctl stop puqvpncp

Step 2: Run Recovery

puqvpncp --recover

This will:

=== PUQVPNCP Recovery Mode ===
[OK] Admin group reset to full access (*)
[OK] Admin user: already in admin group
[OK] Admin password reset to 'admin' (password change will be required)

Recovery complete. Login as admin / admin.
You will be prompted to change the password on first login.

The recovery command performs the following:

Step 3: Start the Service

systemctl start puqvpncp

Step 4: Login

Open the web panel and login with:

Field Value
Username admin
Password admin

You will be prompted to set a new password immediately.

Service Won't Start

Check the service status

systemctl status puqvpncp

Check the logs

tail -100 /var/log/puqvpncp/puqvpncp.log

Common causes

Problem Solution
Port already in use Check WebPort in /etc/puqvpncp/puqvpncp.conf, or stop the conflicting service
SSL certificate error Verify that Domain resolves to this server's IP and port 443 is not in use
Permission denied Ensure the binary is at /usr/sbin/puqvpncp and has execute permissions
Missing dependencies Run Settings > Environment check, or install missing packages manually

Web Panel Not Accessible

Check if the service is running

systemctl is-active puqvpncp

Check which port is in use

ss -tlnp | grep puqvpncp

Common causes

Problem Solution
Firewall blocking the port Allow the port: iptables -I INPUT -p tcp --dport 8098 -j ACCEPT
Wrong listen address Check WebIP in /etc/puqvpncp/puqvpncp.conf (default: 0.0.0.0)
IP restriction active Check AllowedWebIP — set to 0.0.0.0 to allow all IPs
SSL enabled but accessing HTTP With LetsEncrypSSL=yes, use https:// on port 443, not HTTP

Binary Cannot Be Updated

If you get "Text file busy" error when trying to copy a new binary:

systemctl stop puqvpncp
cp puqvpncp /usr/sbin/puqvpncp
systemctl start puqvpncp

The service must be stopped before replacing the binary. The running process locks the file.

WireGuard Interface Not Created

Check if WireGuard kernel module is loaded

modprobe wireguard
lsmod | grep wireguard

Check WireGuard tools

wg --version

If missing, install:

apt install wireguard wireguard-tools

AmneziaWG Interface Not Created or Module Not Loaded

1. Check DKMS status and kernel module

# Check DKMS compilation status
dkms status
# Should show: amneziawg/..., ...: installed

# Check if the kernel module is currently loaded
lsmod | grep amneziawg

# Try loading the module manually
modprobe amneziawg

2. Module build failed or missing (Debian / Ubuntu)

On Debian, DKMS compilation fails if linux-headers-$(uname -r) and build tools are missing. To fix:

# Install kernel headers and build tools for the running kernel
apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)

# Reconfigure and recompile the DKMS module
dpkg-reconfigure amneziawg-dkms

# Load the compiled module into the kernel
modprobe amneziawg

# Verify
lsmod | grep amneziawg

3. Dependency error on Debian 12: Depends: libc6 (>= 2.38)

If apt-get install fails with:

The following packages have unmet dependencies:
 amneziawg-tools : Depends: libc6 (>= 2.38) but 2.36-... is to be installed
E: Unable to correct problems, you have held broken packages.

Cause: Debian 12 (Bookworm) uses glibc 2.36. Ubuntu 24.04 (noble) was added instead of Ubuntu 22.04 (jammy).

Solution: Change noble to jammy in /etc/apt/sources.list.d/amnezia.list:

echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu jammy main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

4. Keyring error or -bash: gpg: command not found

If you encounter:

-bash: gpg: command not found
Error: Failed to parse keyring "/etc/apt/keyrings/amnezia.gpg"
The repository '... noble InRelease' is not signed.

Cause: Minimal Debian installations do not include gpg/gnupg.

Solution: Save the key in native ASCII .asc format directly without piping to gpg:

mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc

5. Repository setup by Debian version

Debian 12 (Bookworm):

apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu jammy main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Debian 13 (Trixie):

apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu noble main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Ubuntu (22.04 / 24.04 LTS):

add-apt-repository -y ppa:amnezia/ppa
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

6. Check AmneziaWG tools

awg --version

5. DNS resolution error when using awg-quick manually

If awg-quick up awg0 fails with resolvconf: command not found on Debian:

apt-get install -y openresolv

Getting Help

21. Diagnostics

Overview

The Diagnostics section provides real-time monitoring, log viewing, and system integrity checking across all VPN protocols, traffic control, monitoring services, and the panel itself.

Navigate to Diagnostics in the main menu to access the following pages:

Diagnostics menu Diagnostics dropdown menu

Page Description
WireGuard WireGuard service status, wg show output, kernel logs
AmneziaWG AmneziaWG service status, awg show output, kernel logs
OpenVPN OpenVPN service status, certificates, instances, connection events, auth log, server logs
IKEv2 strongSwan service status, certificates, ipsec statusall output, IKEv2 logs
Traffic Control Overview of TC classes, per-interface bandwidth statistics with live throughput
Telegraf Telegraf service status, InfluxDB output config, inputs, Telegraf logs
System Server uptime, memory, disk usage, network interfaces, system logs
Panel PUQVPNCP application log viewer (puqvpncp.log)
Integrity Check Full system integrity audit — verifies firewall rules, ipset, routing, TC classes, interfaces

Permission: All diagnostics pages require the diagnostics:read permission. Integrity Check requires firewall:read (audit) and firewall:write (fix).

All log viewers feature:

WireGuard

Diagnostics: WireGuard Diagnostics: WireGuard — service status, wg show, kernel logs

Service Status

Field Description
WireGuard Installed WireGuard kernel module version
WireGuard Tools Installed wireguard-tools package version
Networks Number of WireGuard-enabled networks
Clients Total number of WireGuard clients
Online Number of currently connected WireGuard peers

If WireGuard or WireGuard Tools are not installed, or no networks are configured, a warning alert is displayed with instructions.

wg show

Displays the raw output of the wg show command — the standard WireGuard status tool. Shows all active WireGuard interfaces with their public keys, listening ports, and connected peers with handshake times and transfer statistics.

This section is collapsible. Click the header to expand/collapse.

WireGuard Kernel Logs

Displays WireGuard-related kernel messages from journalctl. These logs show low-level WireGuard events such as interface creation, peer handshake failures, and kernel module messages.

AmneziaWG

Diagnostics: AmneziaWG Diagnostics: AmneziaWG — service status, awg show, and kernel logs

Service Status

Field Description
AmneziaWG Installed AmneziaWG kernel module (DKMS) version
AmneziaWG Tools Installed amneziawg-tools package CLI version (awg)
Networks Number of AmneziaWG-enabled networks
Clients Total number of AmneziaWG clients
Online Number of currently connected AmneziaWG peers

If AmneziaWG or AmneziaWG Tools are not installed, or no networks are configured, an informative warning alert is displayed with repository and package installation instructions for Debian 12 (using Ubuntu 22.04 jammy for glibc compatibility with .asc keyring), Debian 13 (using noble), and Ubuntu (add-apt-repository -y ppa:amnezia/ppa).

awg show

Displays the raw output of the awg show command — the standard AmneziaWG status tool. Shows all active AmneziaWG interfaces with obfuscation parameters (Jc, Jmin, Jmax, S1, S2, H1, H2, H3, H4), public keys, listening ports, and connected peers with handshake times and transfer statistics.

This section is collapsible. Click the header to expand/collapse.

AmneziaWG Kernel Logs

Displays AmneziaWG-related kernel messages from journalctl. These logs show low-level AmneziaWG events such as interface creation, handshake negotiations, and kernel module messages.

OpenVPN

Service Status and Certificates

Diagnostics: OpenVPN — status Diagnostics: OpenVPN — service status, certificates, instances

The page displays two cards side by side:

Service Status:

Field Description
OpenVPN Installed OpenVPN package version
easy-rsa Installed easy-rsa package version
Global Status Whether OpenVPN is globally enabled or disabled
Networks Number of OpenVPN-enabled networks
Online Number of currently connected OpenVPN clients

Certificates:

Field Description
CA Certificate Root CA certificate status (Valid / Not generated / Invalid)
Server Certificate Server TLS certificate status
DH Parameters Diffie-Hellman parameters status
TLS Auth Key HMAC authentication key status

Instances

Shows a table of all OpenVPN network instances:

Column Description
Network Network name (link to network edit page)
Port UDP/TCP port for this instance
Status Running (green) or Stopped (red)
PID Process ID (if running)

Each OpenVPN-enabled network runs as a separate openvpn process with its own PID file.

Connection Events

Diagnostics: OpenVPN — logs Diagnostics: OpenVPN — connection events and authentication log

Displays the OpenVPN connection log (/etc/openvpn/puqvpncp/logs/connections.log). Shows client connect and disconnect events with color coding:

Authentication Log

Displays the OpenVPN authentication log (/etc/openvpn/puqvpncp/logs/auth.log). Shows authentication attempts with color coding:

Server Logs

Diagnostics: OpenVPN — server logs Diagnostics: OpenVPN — server logs from all network instances

Displays combined server logs from all OpenVPN network instances (/etc/openvpn/puqvpncp/logs/*.log). Each log line is prefixed with the network name in square brackets (e.g., [net1] ...).

IKEv2

Service Status and Certificates

Diagnostics: IKEv2 Diagnostics: IKEv2 — service status, certificates, ipsec statusall

The page displays two cards side by side:

Service Status:

Field Description
strongSwan Installed strongSwan version
Starter PID PID of the strongSwan starter process
Charon PID PID of the IKE daemon (charon)
Global Status Whether IKEv2 is globally enabled or disabled
Server Domain Domain configured for IKEv2 server certificates
Online Number of currently connected IKEv2 clients

Certificates:

Field Description
CA Certificate Root CA certificate status (Valid / Not generated / Invalid)
Server Certificate Server certificate status

ipsec statusall

Displays the raw output of the ipsec statusall command — the standard strongSwan status tool. Shows detailed information about:

This section is collapsible.

IKEv2 / strongSwan Logs

Diagnostics: IKEv2 — logs Diagnostics: IKEv2 — strongSwan logs

Displays strongSwan logs from journalctl. Shows IKE negotiation events, connection establishments, certificate validations, and authentication messages. The system tries strongswan unit first, then falls back to charon syslog tag.

Traffic Control

Diagnostics: Traffic Control Diagnostics: Traffic Control — overview and per-interface TC classes

Overview

Field Description
Managed Interfaces Total number of network interfaces with TC rules
Total TC Classes Total number of HTB traffic control classes across all interfaces
Total Bytes Processed Sum of all bytes processed by TC classes
Total Drops Sum of all dropped packets (highlighted in red if > 0)

The overview auto-refreshes every 2 seconds.

Per-Interface Tables

Below the overview, each managed interface is displayed as a separate card showing all its TC classes:

Column Description
Handle TC class handle (e.g., 1:806e)
Type Class type — root for the root class, or direction + protocol (e.g., DL IPv4 #110, UL IPv6 #119)
Rate Configured bandwidth rate
Bytes Total bytes processed by this class
Packets Total packets processed
Drops Dropped packets (highlighted in red if > 0)
Overlimits Overlimit events (highlighted in yellow if > 0)
Throughput Real-time throughput calculated from byte deltas between refreshes

Interfaces include:

Telegraf

Diagnostics: Telegraf Diagnostics: Telegraf — service status, InfluxDB config, inputs, logs

Service Info

Three cards are displayed:

Telegraf Service:

Field Description
Version Installed Telegraf version
Status Running (with PID) or Stopped

InfluxDB Output:

Field Description
Enabled Whether InfluxDB output is enabled
URL InfluxDB server URL
Bucket InfluxDB bucket name
Organization InfluxDB organization

Inputs:

Field Description
Socket Listener Whether the Unix socket input is active (receives metrics from PUQVPNCP)
HTTP Metrics Whether the HTTP metrics endpoint is active

Telegraf Logs

Displays Telegraf service logs from journalctl with color coding:

System

Diagnostics: System Diagnostics: System — uptime, memory, disk usage, interfaces

System Info Cards

Four cards are displayed:

Uptime — output of the uptime command showing server uptime, number of users, and load averages.

Memory — output of free -h showing total, used, free, shared, buffers/cache, and available memory for both RAM and swap.

Disk Usage — output of df -h showing mounted filesystem, size, used space, available space, and usage percentage for the root partition.

Interfaces — output of ip -br addr showing all network interfaces with their status (UP/DOWN) and assigned IP addresses. Includes physical interfaces, WireGuard interfaces, OpenVPN tunnel interfaces, and upstream tunnels.

System Logs (puqvpncp)

Diagnostics: System — logs Diagnostics: System — PUQVPNCP system logs

Displays PUQVPNCP service logs from journalctl (syslog tag puqvpncp). Shows application events such as API requests, system operations, network changes, and service lifecycle events.

Panel Log

Diagnostics: Panel Log Diagnostics: Panel Log — puqvpncp.log viewer

Displays the PUQVPNCP application log file (puqvpncp.log in the configured LogDir directory, default /var/log/puqvpncp/).

This is the application's own log file (separate from journalctl system logs). Log entries are color-coded by level:

The log format is: timestamp LEVEL: message (e.g., 2026-03-11T17:18:00.000Z INFO: ReloadNetworks: setting iptables).

Integrity Check

Integrity Check Integrity Check — summary, log table, and last run info

The Integrity Check performs a comprehensive audit of the entire PUQVPNCP system configuration. It verifies that all firewall rules, routing tables, ipset entries, traffic control classes, and network interfaces are correctly configured and match the expected state.

Running a Check

Two buttons are available in the page header:

Button Description
Audit (magnifying glass) Run a read-only audit — checks all rules and reports issues without making changes
Audit & Fix (wrench) Run an audit and automatically fix any issues found

The check runs in the background. Results stream in real-time via Server-Sent Events (SSE), with automatic polling fallback if SSE disconnects.

Summary

The summary card shows counters for each check result:

Counter Color Description
Total — Total number of checks performed
OK Green Checks that passed
Failed Red Checks that failed (in audit mode, these need fixing)
Fixed Yellow Checks that were failed but successfully repaired (fix mode only)
Errors Blue Checks where the fix was applied but still failing
Skipped Gray Checks that were skipped (e.g., ipset not installed, mangle overflow)

A progress bar shows the proportion of each result type.

Filter Buttons

Filter the log table by status:

Log Table

Column Description
Time Timestamp of the check
Status Result badge (OK / FAILED / FIXED / ERROR / SKIPPED)
Category Check category (see below)
Network Network and/or client name (if applicable)
Description What was checked
Detail Additional information (e.g., "Fixed", error message)

Check Categories

The integrity check performs 9 phases, covering all aspects of the system:

Category Phase What is Checked
System 1 IPv4 forwarding enabled, INPUT/FORWARD/OUTPUT chain policies, system_PUQVPNCP rule
Global Rules 2 Pre-filter rules, peering ACCEPT rules (A→B, B→A), intra-network ACCEPT, isolation DROP (ipset), post-filter rules
ipset 3 puq_vpn_nets ipset exists, each network subnet is a member
Chains 4 Per-network chains exist in filter (PQ_), nat SNAT (PQN_), nat DNAT (PQD_), mangle (PQM_) — plus jump rules from built-in chains
NAT 5 SNAT rules for each network's upstream IP
Mangle 5 Per-client mangle marks for download (dst) and upload (src) traffic
Network Rules 5 Route ACCEPT rules for custom routes
Policy Routing 6 Upstream WG tunnel ip rule / ip route table, WG/OpenVPN fwmark-based policy routing
CONNMARK 7 WG and OpenVPN CONNMARK rules in PREROUTING (mangle)
Traffic Control 8 Root HTB qdisc on gateway, VPN, and upstream interfaces; per-client TC classes
Interfaces 9 WireGuard interfaces are UP, upstream WG tunnel interfaces are UP

Last Run

The Last Run card shows information about the most recent integrity check:

Field Description
Mode audit or fix
Started When the check started
Duration How long the check took
Result Summary of OK, failed, fixed, errors, and skipped counts

22. AmneziaWG (Anti-Censorship)

Overview

AmneziaWG is a specialized fork of WireGuard designed to evade Deep Packet Inspection (DPI) and strict internet censorship systems. While standard WireGuard has easily detectable packet signatures, AmneziaWG obfuscates traffic while retaining WireGuard's speed and performance.

Key Capabilities

Requirement: amneziawg (kernel module or DKMS) and amneziawg-tools packages must be installed on the host. Check via Settings > Environment.

Installation

AmneziaWG requires the kernel module (amneziawg-dkms) and CLI tools (amneziawg-tools). Choose the instructions corresponding to your operating system:

Debian 12 (Bookworm)

Important for Debian 12: Debian 12 uses glibc 2.36. The Ubuntu 24.04 (noble) package requires libc6 >= 2.38, so attempting to use noble will result in broken package dependencies. You must use the Ubuntu 22.04 (jammy) PPA.

The keyring is saved directly in .asc format, so no gpg or gnupg package is required:

# 1. Install build tools, DKMS, and current kernel headers
apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)

# 2. Add the official Amnezia PPA repository keyring (ASCII format)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc

# 3. Add Launchpad PPA source (jammy for Debian 12)
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu jammy main" > /etc/apt/sources.list.d/amnezia.list

# 4. Install the DKMS module and tools
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools

# 5. Load the kernel module
modprobe amneziawg

Debian 13 (Trixie)

On Debian 13, glibc is 2.40+, so the Ubuntu 24.04 (noble) PPA is used:

# 1. Install build tools, DKMS, and current kernel headers
apt-get update && apt-get install -y curl build-essential dkms linux-headers-$(uname -r)

# 2. Add the official Amnezia PPA repository keyring (ASCII format)
mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc

# 3. Add Launchpad PPA source (noble for Debian 13)
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu noble main" > /etc/apt/sources.list.d/amnezia.list

# 4. Install the DKMS module and tools
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools

# 5. Load the kernel module
modprobe amneziawg

Ubuntu (22.04 / 24.04 LTS)

Option 1: Using add-apt-repository (standard):

add-apt-repository -y ppa:amnezia/ppa
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Option 2: Using direct keyring (minimal systems):

mkdir -p /etc/apt/keyrings
curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" -o /etc/apt/keyrings/amnezia.asc
echo "deb [signed-by=/etc/apt/keyrings/amnezia.asc] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Verification

Verify that the module has been compiled and loaded into the kernel:

# Check DKMS compilation status (should show 'installed')
dkms status

# Check that the kernel module is active
lsmod | grep amneziawg

# Check that the awg CLI utility is available
awg --version

Troubleshooting DKMS Compilation & Kernel Updates

If dkms status shows added or error, or if you upgrade the system kernel:

apt-get install -y build-essential dkms linux-headers-$(uname -r)
dpkg-reconfigure amneziawg-dkms
modprobe amneziawg

Note on DNS / resolvconf: If you run awg-quick manually and receive /usr/bin/awg-quick: resolvconf: command not found, install openresolv:

apt-get install -y openresolv

Navigate to VPN Servers > AmneziaWG to access AmneziaWG management. The page provides 5 tabs: Overview, Networks, Settings, Online, and Client Profiles.

Obfuscation Parameters Explained

Parameter Default Description
H1 Random Header type for handshake initiation packets
H2 Random Header type for handshake response packets
H3 Random Header type for cookie reply packets
H4 Random Header type for data transport packets
Jc 4 Number of junk packets injected before handshake (1–128)
Jmin 40 Minimum byte size of junk packets
Jmax 70 Maximum byte size of junk packets
S1 15 Initiation packet junk size in bytes
S2 20 Response packet junk size in bytes

Each network can inherit the global defaults or define custom obfuscation values to match specific ISP bypass requirements.

Overview Tab

AmneziaWG Overview

The Overview tab displays:

Card Description
Service Status Installed amneziawg kernel module and amneziawg-tools package versions
Summary Total number of AmneziaWG networks and clients configured
Online Connections Real-time count of connected AmneziaWG peers with live bandwidth stats

Networks Tab

AmneziaWG Networks

Lists all networks that have AmneziaWG enabled:

Column Description
Name Network name (link to network edit page)
Clients Number of AmneziaWG clients in this network
Interface Interface name (e.g., awg51821)
Network Subnet assigned to this network
Endpoint Server IP and UDP port for AmneziaWG client connections
Bandwidth Upload / download bandwidth limits

Settings Tab

AmneziaWG Settings

Global defaults for AmneziaWG client profiles:

Online Peers Tab

AmneziaWG Online Peers

Shows real-time connected peers with active session data:

Client Profiles Tab

AmneziaWG Client Profiles

Lists all configured AmneziaWG client profiles across networks, indicating network membership, activation status, and cryptographic key status.

Network Configuration

Network Edit — AmneziaWG

When configuring AmneziaWG inside a network:

Client Configuration & QR Codes

Client Edit — AmneziaWG

In the client management page, enabling AmneziaWG automatically generates:

  1. Standard cryptographic keys adapted for AmneziaWG
  2. Obfuscation parameters embedded into client .conf
  3. QR code for instant mobile setup via AmneziaWG apps on iOS and Android

OTL AmneziaWG Configuration

Administrators can configure the AmneziaWG download page on One-Time Links, setting custom button labels and download links for all supported platforms (Android, iOS, Windows, macOS).

OTL AmneziaWG Client View

The end-user sees a clean, self-service page with QR code, configuration preview, config file download button, and direct app store links to the official AmneziaWG clients.