Mikrotik WireGuard VPN WHMCS module
WHMCS server provisioning module for automated WireGuard VPN deployment on Mikrotik routers. Supports full lifecycle management, bandwidth shaping, atomic traffic statistics, post-paid metric billing, QR code configuration, human-readable traffic metrics, and multilingual client/admin interfaces.
- Description
- Changelog
- Installation and Configuration Guide
- Setup Guide: Mikrotik Preparation and Configuration
- WHMCS Installation and Update
- Product Configuration
- Add Server (Router Mikrotik) in WHMCS
- Admin Area
- Client Area
Description
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
PUQ Mikrotik WireGuard VPN — WHMCS Server Module
PUQ Mikrotik WireGuard VPN is a WHMCS server provisioning module for automated deployment of WireGuard VPN accounts on Mikrotik routers. The module communicates with Mikrotik via REST API and provides full lifecycle management of VPN services including creation, suspension, unsuspension, termination, and package changes.
Key Features
- Automatic WireGuard VPN provisioning — create and deploy VPN accounts on Mikrotik routers automatically
- Full lifecycle management — create, suspend, unsuspend, terminate, and change packages
- Mikrotik REST API only — communicates exclusively via Mikrotik REST API (RouterOS 7+) with 15s connection timeout protection
- Bandwidth speed limits — configurable upload/download speed limits per product using Mikrotik Simple Queues
- Private and public IP support — assign IPs from a configurable pool per server
- Metric billing — post-paid usage-based billing for incoming and outgoing traffic (GB) via standard WHMCS MetricProvider
-
WireGuard configuration export — text and dynamic QR code formats with one-click
.conffile download - VPN connection status monitoring — real-time endpoint, handshake, and transfer statistics dynamically formatted in human-readable units (B, KB, MB, GB, TB)
- Reset VPN Interface — disconnect and reset frozen connections from client or admin area
- Atomic traffic statistics — daily and monthly traffic charts with Google Charts, backed by atomic database increments (can be disabled per product)
- Multilingual interface — 26 languages: Arabic, Azerbaijani, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Farsi, French, German, Hebrew, Hungarian, Italian, Macedonian, Norwegian, Polish, Romanian, Russian, Spanish, Swedish, Turkish, Ukrainian
- Custom links — configurable links to setup instructions and VPN client downloads in client area
Available Options in the Admin Panel
- Create / Suspend / Unsuspend / Terminate users
- Change package (update bandwidth limits and WireGuard interface)
- VPN connection status and peer information
- Reset VPN Interface function
- Text and QR code configuration display
- Metric Billing (Bandwidth Usage Download/Upload in GB)
Available Options in the Client Panel
- VPN connection status (endpoint, handshake, RX/TX in human-readable units)
- Text and QR code configuration with download button
- Reset VPN Interface function
- Traffic statistics with daily and monthly charts
- Links to user manual and VPN client downloads
System requirements
| Requirement | Minimum |
|---|---|
| WHMCS | 8.x+, 9.x+ |
| PHP | 7.4, 8.1, 8.2, 8.3, 8.4 |
| ionCube Loader | v15+ |
| Mikrotik RouterOS | 7.x+ |
Important Notes
- The upload and download speed settings in the WHMCS module register the opposite values on the Mikrotik router (e.g., download speed in WHMCS = upload speed in Mikrotik).
- To ensure proper VPN functionality, the administrator must correctly configure the Mikrotik router: NAT, Firewall, routing, and all required settings for VPN to operate correctly.
Links
- Product page: https://puqcloud.com/whmcs-module-mikrotik-wireguard-vpn.php
- Documentation: https://doc.puq.info/books/mikrotik-wireguard-vpn-whmcs-module
- Support: https://puqcloud.com/submitticket.php
- Community: https://community.puqcloud.com/
Screenshots
Client area — Overview
client-area-overview.png
Client area — Traffic statistics
traffic-statistics.png
Client area — Usage metrics
client-area-metrics.png
Admin area — Product information
admin-product-info.png
Changelog
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
v4.1.0 — 2026-09-30
- Fault-Tolerant Cron & Usage Tracking. Daily usage updates and metric harvesting tasks in WHMCS automation are now strictly isolated per WireGuard service. Any momentary network loss or unreachable router will be safely logged without interrupting the synchronization of remaining customer accounts.
-
PHP 8.x Type Safety Hardening. Thoroughly hardened typed property handling across bandwidth and package limits, preventing
TypeErrorexceptions on PHP 8.1, 8.2, and 8.3 environments. -
Zero-Touch Settings Auto-Migration. Existing WireGuard products configured on legacy schemas automatically upgrade their settings into modern unified parameters (
configoption24) upon product saving, ensuring smooth maintenance. - Enhanced Select2 & WHMCS 9 Admin UX. Upgraded dynamic settings panel detection to guarantee instant and reliable form reactivity across WHMCS 9 and Select2 interfaces.
-
Clean Module Logging. Excluded local database license verification checks (
License_Verification (db)) from the WHMCS Module Log, recording exclusively online verification calls to keep diagnostic logs clean.
v4.0.0 — 2026-09-22
-
WireGuard Simple Queue and metric collection fix. Resolved router 404 errors caused by slashes (
%2F) in Base64 public keys in REST API paths by introducingapiFindQueue()with dedicated IP (target=.../32) and query-parameter lookups. Queue deletion and counter resets are now executed reliably via internal RouterOS.id. -
Atomic traffic statistics collection. Replaced read-modify-write logic with atomic SQL increments (
Capsule::raw) inStatisticsSaveTraffic(), eliminating race conditions and traffic data loss during concurrent WHMCS cron jobs and metric queries. -
WHMCS Usage Billing MetricProvider fix. Resolved zero-traffic reporting so that
Usage(0.0)is reliably returned when usage is 0 GB, preventing "No usage data" statuses in WHMCS. -
Human-readable Transfer RX & TX units. Replaced raw byte integers in the client area with dynamically formatted units (
B,KB,MB,GB,TB) with 2-decimal precision. - Admin API connection timeout and performance optimization. Enforced a strict 15-second timeout on router status checks and removed early blocking API calls from constructor, eliminating admin panel delays and cron execution lags.
- PHP 7.4 & PHP 8.x compatibility. Resolved syntax compatibility issues across PHP 7.4 through PHP 8.4.
-
ionCube 15 & PHP 8.2+ architectural upgrade. Transitioned
hooks.phpto an unencoded lightweight bootstrap delegating logic tolib/puqMikrotikWireGuardVPNHooks.phpfor seamless ionCube 15 compatibility. -
Automated usage cleanup on termination. Local usage statistics in
puqMikrotikWireGuardVPN_statisticsare now automatically purged when a service is terminated. -
Enhanced Client Area UI. Integrated standard PUQ client area UI toolkit with
header.tpl, QR code rendering, dynamic config download, copy-to-clipboard, CSRF protection, and streamlined layout. - Legacy configuration fallback. Added transparent backward compatibility for products migrating from older configuration schemas.
v3.2.1 — 2026-06-02
- Full compatibility with the latest Mikrotik RouterOS 7.21.4. The module has been tested and certified against RouterOS 7.21.4, so you can confidently run the newest firmware on your routers without any provisioning hiccups.
- Rock-solid REST API connections. Resolved rare cases where requests to the router could stall and time out, leaving operations hanging. Account creation, suspension, statistics collection and status checks now complete instantly and reliably.
- Snappier, more dependable automation. With every API call responding without delay, day-to-day provisioning and billing run faster and smoother — fewer retries, no stuck tasks, and a more responsive experience for both your team and your customers.
- PHP 7.4 support restored. The module once again runs on PHP 7.4 in addition to PHP 8.x, so hosting environments that have not yet migrated to PHP 8 can keep using the latest version. PHP 7.4 will remain supported for as long as it is technically possible to do so.
v3.2 — 2026-04-21
- Improved stability across the WHMCS admin area. Rare page-loading errors that could appear on some admin screens (for example when opening a support ticket on installations with non-standard file layouts, symlinks or custom hosting paths) have been eliminated. The admin panel now loads smoothly in every environment.
- Greater compatibility with complex hosting setups. The module is now fully resilient to WHMCS installations using symlinked directories, multi-domain hosting and custom include paths.
- Smoother day-to-day operation for administrators. Fewer interruptions, no unexpected "Oops!" pages, and a more predictable experience when working with tickets, clients and services — so your team can focus on customers, not on troubleshooting.
v3.1 — 2026-02-26
New Features
- Added option to disable traffic statistics collection per product
- When statistics collection is disabled, traffic data is not collected and the statistics page is hidden from the client area
v3.0 — 2026-02-02
Changes
- Support for WHMCS 9+ with redesigned product module settings
- Updated client area interface design
- New admin settings UI with custom panels (Mikrotik & Bandwidth, WireGuard Configuration, History, Client Area)
- Configuration stored as JSON in configoption24 instead of individual config options
Warning: Product reconfiguration is required after update from v2.x.
v2.0 — 2024-09-23
Changes
- Module is coded with ionCube v13
- Supports PHP 7.4, 8.1, and 8.2 with WHMCS 8.11.0 and later versions
v1.3 — 2024-07-29
New Features
- Added metric pricing for incoming and outgoing traffic (Bandwidth Usage Download/Upload in GB)
v1.2 — 2024-06-17
New Features
- Implemented VPN interface reboot capability for connection resets
Improvements
- Improved mobile client area adaptation
- Minor translation adjustments
v1.1 — 2023-12-15
New Features
- Package change functionality introduced
Improvements
- Minor administrative and client interface modifications
v1.0 — 2023-10-09
First release.
Features
- Automatic creation and deployment of WireGuard VPN accounts on Mikrotik routers
- Suspend, unsuspend, and terminate VPN accounts
- Integration with Mikrotik REST API only (RouterOS 7+)
- Configurable bandwidth speed limits (upload/download)
- Support for private and public IP addresses
- IP address pool management per server
- Text and QR code WireGuard configuration formats
- VPN connection status monitoring (endpoint, handshake, RX/TX)
- Traffic statistics with daily and monthly charts
- Client area with configuration download and connection info
- Admin area with peer management and API status
- Multilingual support (25 languages)
- License verification system
Installation and Configuration Guide
Step-by-step instructions for installing the module, preparing the Mikrotik router, and configuring WHMCS products and servers.
Setup Guide: Mikrotik Preparation and Configuration
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
Prerequisites
- RouterOS version 7 or higher is required.
- Access to the Mikrotik router via terminal (SSH, Winbox terminal, or WebFig terminal).
Important: Enter the following commands one by one and wait for each command to complete before proceeding to the next.
Step I. Check RouterOS Version
Verify that your router is running RouterOS 7 or higher:
system/package/print
Step II. Create Root Certificate Authority
Create a local CA certificate for SSL:
/certificate add name=LocalCA common-name=LocalCA key-usage=key-cert-sign,crl-sign
Step III. Sign the CA Certificate
/certificate sign LocalCA
Step IV. Create Webfig Certificate
Replace XXX.XXX.XXX.XXX with the router's public IP address:
/certificate add name=Webfig common-name=XXX.XXX.XXX.XXX
Step V. Sign the Webfig Certificate
/certificate sign Webfig ca=LocalCA
Step VI. Enable SSL for the Web Interface
/ip service set www-ssl certificate=Webfig disabled=no
Step VII. Enable API-SSL
/ip service set api-ssl certificate=Webfig disabled=no
Step VIII. WireGuard VPN Server Setup
Create and enable the WireGuard VPN server interface through the RouterOS interface.
You can do this via Winbox or WebFig:
mikrotik-wireguard-setup.png
Step IX. Configure Firewall, NAT and Routing
Important: Please be aware that to ensure proper functionality of VPN connections, it is essential for you, as an administrator, to correctly configure the Mikrotik router. This entails configuring NAT, Firewall, routing, and all the required settings for VPN to operate correctly.
Example NAT masquerade rule (adjust to your network):
/ip firewall nat add chain=srcnat out-interface=ether1 action=masquerade
Example firewall rule to allow WireGuard traffic:
/ip firewall filter add chain=input protocol=udp dst-port=13231 action=accept comment="Allow WireGuard"
Next Steps
After completing the Mikrotik preparation, proceed to Add server (router Mikrotik) in WHMCS.
WHMCS Installation and Update
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
System requirements
| Requirement | Minimum |
|---|---|
| WHMCS | 8.x+, 9.x+. |
| PHP | 7.4, 8.1, 8.2, 8.3, 8.4 |
| ionCube Loader | v15+ |
| Mikrotik RouterOS | 7.x+ |
Note: The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.
Installation
Note: The module now uses ionCube 15, which provides universal out-of-the-box support for all encodings.
All versions can be found at this link:
https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/Older module versions for WHMCS 8 are available in the archive directory:
https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/archive/
-
Download the latest version from the PUQ download page:
wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip -
Unzip the archive:
unzip PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip -
Copy the
puqMikrotikWireGuardVPNdirectory into your WHMCS installation undermodules/servers/:cp -r puqMikrotikWireGuardVPN /path/to/whmcs/modules/servers/The resulting directory structure should look like:
modules/ servers/ puqMikrotikWireGuardVPN/ puqMikrotikWireGuardVPN.php hooks.php lib/ templates/ lang/ ...
Update
The update process is identical to the installation:
-
Download the latest archive from the download page:
wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip -
Unzip the archive:
unzip -o PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip -
Replace the existing
puqMikrotikWireGuardVPNdirectory in your WHMCS installation:cp -r puqMikrotikWireGuardVPN /path/to/whmcs/modules/servers/
Warning: When updating from v2.x to v3.x+, product reconfiguration is required due to the new settings storage format.
Product Configuration
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
Add new product to WHMCS
- Log in to your WHMCS Admin Area.
- Navigate to System Settings → Products/Services → Create a New Product.
- Fill in the product details (name, description, pricing).
- Go to the Module Settings tab.
- Select PUQ Mikrotik WireGuard VPN from the Module Name dropdown.
- Enter your License key in the corresponding field.
- Configure the remaining module parameters.
- Click Save Changes.
product-configuration.png
Configuration parameters
| Parameter | Description | Default |
|---|---|---|
| License key | Pre-purchased license key for the module. | |
| WireGuard Interface | Name of the WireGuard interface on the Mikrotik router (must be pre-created) | wg1 |
| Comment prefix | Prefix added to VPN peer and queue comments on Mikrotik | whmcs |
| Upload (Mbs/s) | Upload bandwidth speed limit in Mbps | 5 |
| Download (Mbs/s) | Download bandwidth speed limit in Mbps | 5 |
| Allowed IPs | IP ranges allowed to route through the VPN tunnel | 0.0.0.0/0, ::/0 |
| DNS Servers | DNS servers to use when connected to VPN (comma-separated) | 8.8.8.8, 1.1.1.1 |
| Persistent Keepalive | Interval for sending keepalive packets (seconds) | 25 seconds |
| Disable statistics collection | When enabled, traffic statistics will not be collected and the statistics page will be hidden from the client area | Unchecked |
| Save history (days) | Number of days to keep usage statistics in WHMCS (minimum 32 days) | 32 |
| Link to instruction | URL to setup instructions (displayed in client area as "User manual" button) | Empty |
| Custom HTML | Custom HTML content for WireGuard protocol (displayed in client area) | Empty |
Allowed IPs examples:
-
0.0.0.0/0, ::/0— route all IPv4 and IPv6 traffic through VPN (full tunnel) -
10.0.0.0/8, 192.168.0.0/16— route only specific networks (split tunnel)
Recommended: Set "Link to instruction" to https://www.wireguard.com/install/ — the official WireGuard client downloads page.
product-config-mikrotik-bandwidth.png
product-config-wireguard.png
product-config-history.png
product-config-client-area.png
Metric Billing
The module supports usage-based billing through WHMCS Metric Billing. Two metrics are available:
- Bandwidth Usage Download (GB) — monthly download traffic in gigabytes
- Bandwidth Usage Upload (GB) — monthly upload traffic in gigabytes
To enable metric billing, go to the product's Metric Billing section and toggle the desired metrics ON, then click Configure Pricing to set the per-GB price.
metric-billing.png
metric-billing-download.png
metric-billing-upload.png
Add Server (Router Mikrotik) in WHMCS
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
Step 1: Name and Hostname
- Name — a descriptive name for your convenience (e.g., "Mikrotik VPN Router 1")
-
Hostname — the hostname that resolves to your Mikrotik router's IP address (e.g.,
vpn.mydomain.com). You can also use a dedicated domain. The important thing is that the chosen hostname resolves to the IP address of the Mikrotik router in your DNS.
Step 2: Assigned IP Addresses
In the Assigned IP Addresses field, enter a list of IP addresses that will be issued to VPN clients — one IP per line.
These IPs will be assigned to WireGuard peers as their tunnel addresses. The module automatically allocates the first available (unused) IP from this pool for each new service.
whmcs-server-ips.png
Step 3: Server Details
- Select the "PUQ Mikrotik WireGuard VPN" module from the Module dropdown
- Enter the correct username and password for the Mikrotik router
- Set the port (default:
443for HTTPS REST API) - Check the Secure checkbox if using HTTPS (recommended)
whmcs-server-details.png
Step 4: Test Connection
Click the "Test Connection" button to verify that WHMCS can communicate with the Mikrotik router via REST API.
A successful connection will confirm that:
- The Mikrotik router is reachable
- The credentials are correct
- The REST API is enabled and responding
Next Steps
After adding the server, proceed to Product Configuration in WHMCS.
Admin Area
The administrator interface for managing WireGuard VPN service instances.
Product Information
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
The admin service management page provides a comprehensive view of each VPN service instance.
admin-product-info.png
License Verification
Displays the license status for the product. If the license is invalid or expired, an error message is shown.
API Connection Status
Shows whether WHMCS can successfully communicate with the Mikrotik router:
- API Connection OK — the Mikrotik router is reachable and responding
- API connection problem — the router is unreachable or credentials are incorrect
Peer Status
Indicates whether the WireGuard peer exists on the Mikrotik router and its current state:
- Disabled: false — the peer exists and is active (green indicator)
- Disabled: true — the peer exists but is disabled/suspended (red indicator)
- The peer does not exist on the VPN server — no peer found for this service
Peer Info
A table displaying detailed peer information:
| Field | Description |
|---|---|
| publicKey | The client's WireGuard public key |
| Endpoint | The client's current IP address and port (N/A if not connected) |
| Latest handshake | Timestamp of the last successful WireGuard handshake (N/A if never connected) |
| Transfer RX | Total data received by the peer |
| Transfer TX | Total data sent by the peer |
Config
Displays the WireGuard client configuration in two formats:
- QR Code — scannable QR code image
- Text config — the full WireGuard configuration text
Admin Actions
The following management actions are available:
| Action | Description |
|---|---|
| Create | Generate WireGuard keys, allocate IP, create peer and bandwidth queue on Mikrotik |
| Suspend | Disable the WireGuard peer on Mikrotik |
| Unsuspend | Re-enable the WireGuard peer on Mikrotik |
| Terminate | Delete the peer and queue from Mikrotik, clear service data |
| Change Package | Update the peer's WireGuard interface and recreate the bandwidth queue with new limits |
| Reset VPN Interface | Temporarily disable and re-enable the peer to reset a frozen connection |
Client Area
The client-facing interface for managing WireGuard VPN services.
Home Screen
Mikrotik WireGuard VPN module WHMCS
Order now | Download | Community
Customers accessing their VPN service panel can view and manage their WireGuard VPN connection.
Overview and Sidebar
- Overview > Information — the main dashboard with VPN details.
- Overview > Traffic statistics — daily and monthly usage graphs.
- Actions — quick links to reset the interface, upgrade/downgrade, or request cancellation.
client-area-sidebar.png
Action Buttons
At the top of the main page, the following buttons are displayed:
- User manual — link to setup instructions (if configured by administrator)
- Reset VPN Interface — reboot the VPN interface to reset a frozen connection
Network Configuration
Displays the VPN service status and settings:
- Enable — shows whether the VPN peer is enabled or disabled
- VPN Protocol — always "WireGuard"
- Bandwidth download/upload — the configured speed limits in Mb/s
Connection Status
Real-time information about the VPN connection:
- Endpoint — the client's current IP address and port (shown when connected)
- Latest handshake — timestamp of the last successful WireGuard handshake
- Transfer RX — data received by the peer (formatted dynamically in B, KB, MB, GB, TB)
- Transfer TX — data sent by the peer (formatted dynamically in B, KB, MB, GB, TB)
WireGuard Configuration
Provides the client with everything needed to configure their WireGuard client:
-
DOWNLOAD CONFIG button — downloads the
wg0.confconfiguration file - Copy Configuration button — copies the text configuration to clipboard
- QR Code — scannable QR code for mobile WireGuard apps
- Configuration text — the full WireGuard configuration in text format
- Custom HTML — any custom HTML content defined by the administrator
The configuration includes:
[Interface]
Address = <client VPN IP>
DNS = <configured DNS servers>
PrivateKey = <client private key>
[Peer]
PersistentKeepalive = <configured keepalive>
Endpoint = <server hostname>:<WireGuard listen port>
PublicKey = <server public key>
AllowedIPs = <configured allowed IPs>
client-area-overview.png
Traffic Statistics
When traffic statistics collection is enabled (default), a Traffic statistics link appears in the sidebar navigation.
The statistics page displays two charts powered by Google Charts:
- Traffic statistics for the last 30 days — daily download and upload traffic in GB
- Total traffic for all time per month — monthly aggregated download and upload traffic in GB
traffic-statistics.png
Note: Traffic statistics can be disabled per product in the admin settings (History > Disable statistics collection). When disabled, the sidebar link and statistics page are hidden.
Usage Metrics (Metric Billing)
When WHMCS Usage-based Metric Billing is enabled for the product, clients can navigate to the Metrics tab alongside Manage in their service view:
- Displays current usage for Bandwidth Usage Download (GB) and Bandwidth Usage Upload (GB).
- Shows pricing information per GB and when metrics were last updated.
client-area-metrics.png