# Installation and Configuration Guide Step-by-step instructions for installing, configuring, and setting up the Mikrotik VPN WHMCS module, including Mikrotik router preparation (RouterOS certificates, HTTPS and API-SSL, VPN server), WHMCS integration, email templates, server registration, and product configuration. # WHMCS setup (install/update) ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## System requirements | Requirement | Minimum version | |-------------|-----------------| | **PHP** | 8.2 or higher | | **WHMCS** | 9.x or higher | | **Mikrotik RouterOS** | 7.x or higher | | **ionCube Loader** | v13 or newer (v14, v15) | > **Note:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server. --- ## Download The module can be ordered and downloaded from PUQ Cloud: - **Order / Download:** [https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) - **FAQ:** [https://faq.puqcloud.com/](https://faq.puqcloud.com/) - **Direct download link for the latest version:** ``` wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php82/PUQ_WHMCS-Mikrotik-VPN-latest.zip ``` > Older module versions for WHMCS 8 are available in PHP-specific directories: > - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/) > - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/) After downloading, extract the archive: ``` unzip PUQ_WHMCS-Mikrotik-VPN-latest.zip ``` --- ## Installation ### Step 1: Upload files Extract the module archive and copy the `puqMikrotikVPN` directory to the WHMCS servers module directory: ``` WHMCS_WEB_DIR/modules/servers/puqMikrotikVPN ``` ### Step 2: Add server Navigate to **System Settings** → **Servers** → **Add New Server**: 1. Enter the correct **Name** and **Hostname** 2. In **Assigned IP Addresses**, enter the list of IPs to distribute to users 3. In Server Details, select the **PUQ Mikrotik VPN** module 4. Enter valid Mikrotik router credentials (username and password) 5. Click **Test connection** to verify ### Step 3: Create product Navigate to **System Settings** → **Products/Services** → **Create a New Product**: 1. Select the **PUQ Mikrotik VPN** module in the Module settings section 2. Configure the product parameters --- ## Update ### Step 1: Backup Before updating, it is recommended to back up: - WHMCS database - Module files in `modules/servers/puqMikrotikVPN/` ### Step 2: Upload new files Download and extract the new version, then overwrite all files in: ``` WHMCS_WEB_DIR/modules/servers/puqMikrotikVPN/ ``` ### Step 3: Verification 1. Log in to the WHMCS admin panel 2. Check the module is functioning correctly 3. Verify product settings > **Important (v3.0):** Product reconfiguration is required after updating to version 3.0. The traffic package model has been replaced with post-paid billing via WHMCS metrics. # Setup guide: Mikrotik preparation and configuration ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) This guide covers the preparation of a Mikrotik router for use with the PUQ Mikrotik VPN WHMCS module: root CA certificate, Webfig certificate, HTTPS, API-SSL and VPN server activation. > **Note:** Enter the following commands one by one and wait for each command to complete before running the next. --- ## 1. Check RouterOS version Ensure RouterOS version is 7.x or higher: ``` system/package/print ``` --- ## 2. Create a root CA on the router Enable HTTPS by creating your own local root Certificate Authority: ``` /certificate add name=LocalCA common-name=LocalCA key-usage=key-cert-sign,crl-sign ``` --- ## 3. Sign the root CA certificate ``` /certificate sign LocalCA ``` --- ## 4. Create a non-root certificate for Webfig > Replace `XXX.XXX.XXX.XXX` with your router's public IP address (or the hostname you use to reach it). ``` /certificate add name=Webfig common-name=XXX.XXX.XXX.XXX ``` --- ## 5. Sign the Webfig certificate with the local CA ``` /certificate sign Webfig ca=LocalCA ``` --- ## 6. Enable HTTPS (www-ssl) with the Webfig certificate ``` /ip service set www-ssl certificate=Webfig disabled=no ``` --- ## 7. Enable API-SSL with the Webfig certificate The PUQ Mikrotik VPN module communicates with the router through the **API-SSL** service: ``` /ip service set api-ssl certificate=Webfig disabled=no ``` > **Important:** The module uses the Mikrotik API only. Make sure the API-SSL port is reachable from the WHMCS server. --- ## 8. Enable VPN server Enable the VPN protocol(s) you plan to offer to clients (PPTP, L2TP, etc.) and configure the corresponding PPP profile, service and IP pool. The PPP profile name configured here will later be selected in the product settings on the WHMCS side. ![Mikrotik VPN server setup](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-d62sok6d.png) *16-mikrotik-setup.png* --- ## 9. Firewall, NAT and routing Configure NAT, firewall and routing on the Mikrotik router so that VPN clients can reach the Internet and any internal resources you want to expose. The module itself only provisions the user account (PPP secret) — the surrounding network configuration is the responsibility of the router administrator. > **Important:** The module registers opposite values for upload and download speeds in the Mikrotik router compared to the WHMCS product settings, because Mikrotik measures incoming traffic while VPN clients experience outgoing traffic. # Setup guide: WHMCS setup ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## System requirements | Requirement | Minimum version | |-------------|-----------------| | **PHP** | 8.2 or higher | | **WHMCS** | 9.x or higher | | **Mikrotik RouterOS** | 7.x or higher | | **ionCube Loader** | v13 or newer (v14, v15) | > **Note:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server. > Older module versions for WHMCS 8 are available in PHP-specific directories: > - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/) > - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/) --- ## Step 1: Download the module ```bash wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php82/PUQ_WHMCS-Mikrotik-VPN-latest.zip ``` --- ## Step 2: Extract the archive ```bash unzip PUQ_WHMCS-Mikrotik-VPN-latest.zip ``` --- ## Step 3: Copy module files Copy the `puqMikrotikVPN` directory to: ``` WHMCS_WEB_DIR/modules/servers/ ``` --- ## Step 4: Add server in WHMCS Navigate to **System Settings** → **Servers** → **Add New Server** 1. Enter the correct **Name** and **Hostname** 2. In **Assigned IP Addresses**, enter the list of IPs that will be distributed to users 3. In the Server Details section, select the **PUQ Mikrotik VPN** module 4. Enter valid Mikrotik router credentials (username and password) 5. Click **Test connection** to verify the connection ![Add server - general settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-injeplej.png) *04-add-server-1.png* ![Add server - module settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-rrlnzyut.png) *05-add-server-2.png* --- ## Step 5: Create product in WHMCS Navigate to **System Settings** → **Products/Services** → **Create a New Product** Select the **PUQ Mikrotik VPN** module in the Module settings section. ![WHMCS product module settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-o6xr27tg.png) *06-whmcs-setup.png* # Email Template (puqMikrotikVPN notification traffic limit) ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## Creating the email template Navigate to **System Settings** → **Email Templates** → **Create New Email Template** This template is used to notify the customer when the remaining traffic falls below the threshold configured in the product settings ("Notification traffic remainder less than X GB"). --- ## Template configuration | Parameter | Value | |-----------|-------| | **Email Type** | Product/service | | **Unique Name** | puqMikrotikVPN notification traffic limit | --- ## Email subject ``` Traffic less than {$notification_traffic_remainder} GB - {$username} ``` --- ## Email body ``` Dear {$client_name}, This letter informs you that the traffic limit of the service is coming to an end. Product/Service: {$service_product_name} Due Date: {$service_next_due_date} Username: {$username} Left traffic: {$traffic_balance_gb} GB After renewing the service, {$traffic_billingcycle_gb} GB will be automatically added. {$signature} ``` --- ## Available template variables The following custom variables are passed to the email template by the module: | Variable | Description | Example | |----------|-------------|---------| | `{$username}` | VPN account username | mikrotik-user-42 | | `{$notification_traffic_remainder}` | Traffic threshold configured in product settings (GB) | 5 | | `{$traffic_balance_gb}` | Remaining traffic balance for the customer (GB) | 4.2 | | `{$traffic_billingcycle_gb}` | Traffic that will be added on the next billing cycle (GB) | 100 | In addition, all standard WHMCS product/service merge fields are available (e.g. `{$client_name}`, `{$service_product_name}`, `{$service_next_due_date}`, `{$signature}`). > **Note:** Notifications are sent automatically during the WHMCS cron execution when remaining traffic falls below the threshold configured in the product settings. --- ## Screenshots ![Email template creation](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-5qihi70s.png) *07-email-template-1.png* ![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-n5725aro.png) *08-email-template-2.png* # Email Template (puqMikrotikVPN Suspension Notification traffic limit) ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## Creating the email template Navigate to **System Settings** → **Email Templates** → **Create New Email Template** This template is used to notify the customer that the VPN account has been **suspended on the Mikrotik router** because the traffic balance reached zero or below. The traffic limit will be restored on the next billing cycle. --- ## Template configuration | Parameter | Value | |-----------|-------| | **Email Type** | Product/service | | **Unique Name** | puqMikrotikVPN Suspension Notification traffic limit | --- ## Email subject ``` Suspension Information - {$username} ``` --- ## Email body ``` Dear {$client_name}, This letter informs you that the VPN account has been suspended due to traffic exhaustion. The traffic limit will be restored from the next service cycle. It is also possible to switch to a package with a large amount of traffic. Product/Service: {$service_product_name} Due Date: {$service_next_due_date} Username: {$username} Left traffic: {$traffic_balance_gb} GB After renewing the service, {$traffic_billingcycle_gb} GB will be automatically added. {$signature} ``` --- ## Available template variables The same custom variables as in the traffic-limit notification template are available: | Variable | Description | |----------|-------------| | `{$username}` | VPN account username | | `{$traffic_balance_gb}` | Remaining traffic balance (GB) — normally zero or below when this template is sent | | `{$traffic_billingcycle_gb}` | Traffic that will be added on the next billing cycle (GB) | Plus all standard WHMCS product/service merge fields (`{$client_name}`, `{$service_product_name}`, `{$service_next_due_date}`, `{$signature}`). > **Note:** This email is sent automatically by the module when the VPN account is auto-suspended on the Mikrotik router because the customer's traffic balance has been exhausted. # Add server (Mikrotik router) ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## Adding a Mikrotik router to WHMCS Configure a Mikrotik router as a server within WHMCS using the PUQ Mikrotik VPN module. Navigate to **System Settings** → **Servers** → **Add New Server** --- ### Step 1: General settings Enter the correct **Name** and **Hostname** for your Mikrotik router. - **Name** — an internal identification for the server (e.g. "My great Mikrotik router") - **Hostname** — a resolvable domain pointing to the router's IP address (e.g. `vpn.mydomain.com`) If your Mikrotik API-SSL service listens on a non-standard port, enter it in the **Port** field. Check the **Secure** checkbox (the module talks to the router through API-SSL). ![Add server - general settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-sih9y7ai.png) *04-add-server-1.png* --- ### Step 2: Assigned IP addresses In the **Assigned IP Addresses** field, enter the list of IP addresses that will be distributed to users. These IPs are consumed sequentially as new VPN accounts are provisioned. Both private and public IP addresses are supported. --- ### Step 3: Module settings 1. In the Server Details section, select the **PUQ Mikrotik VPN** module from the dropdown 2. Enter valid Mikrotik router credentials: - **Username** — Mikrotik user with API access (typically with the `full` group or custom group that includes `api`, `write`, `read`, `policy`) - **Password** — the corresponding password 3. Click **Test connection** to verify the connection is working correctly The test connection verifies that the module can reach the Mikrotik API-SSL service and authenticate with the provided credentials. ![Add server - module settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-pdji3qgn.png) *05-add-server-2.png* > **Important:** The Mikrotik user must have sufficient privileges to create and manage PPP secrets, read traffic counters and reset them. The module uses the Mikrotik API only — SSH access is not used. # Product Configuration ### Mikrotik VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/) | [FAQ](https://faq.puqcloud.com/) ## Add new product to WHMCS Navigate to **System Settings** → **Products/Services** → **Create a New Product** Select the **PUQ Mikrotik VPN** module in the Module settings section. --- ## Configuration parameters | Parameter | Description | |-----------|-------------| | **License key** | A pre-purchased license key for the PUQ Mikrotik VPN module. The license must be active for correct operation. After saving, the verification status is displayed below the field. | | **Comment PREFIX** | Prefix applied to the VPN user comments on the Mikrotik router. Helps identify which PPP secrets belong to WHMCS-managed accounts. | | **Profile** | PPP secret profile on the Mikrotik router. The dropdown is populated with the profiles configured on the selected server. | | **Service** | Available VPN service on the Mikrotik router (e.g. `any`, `pptp`, `l2tp`, `pppoe`, etc.). | | **Bandwidth Download** | Download speed limit in M/s applied to the VPN account. | | **Bandwidth Upload** | Upload speed limit in M/s applied to the VPN account. | | **Traffic (One Time / Monthly / Quarterly / Semi-Annual / Annual / Biennial / Triennial)** | Packet of traffic added per billing cycle (in GB). Values match the WHMCS billing cycle of the product. | | **Save traffic history (days)** | Number of days to retain daily traffic usage statistics. Older records are deleted automatically during cron execution. | | **User notification traffic limit email template** | Email template sent when remaining traffic falls below the threshold configured in the next field. Select a Product/service email template (created manually in WHMCS). | | **Notification traffic remainder less than X GB** | Traffic threshold (in GB) that triggers the notification email. | | **Suspend exceeding traffic limit email template** | Email template sent when the traffic balance reaches zero or below and the VPN account is automatically suspended on the router. | | **Link to instruction** | Optional URL to a client-facing setup manual. Displayed as a button in the client area. Leave empty to hide the button. | | **Support PPtP** | Toggles the display of PPtP connection details (server address, credentials) in the client area. | | **Support L2TP** | Toggles the display of L2TP connection details in the client area. | | **L2TP IPSec PSK key** | The IPSec pre-shared key for L2TP; displayed in the client area when L2TP support is enabled. | | **Statistics collection frequency** | The frequency at which traffic usage statistics are collected by the WHMCS cron. Also checks the traffic balance and disables the VPN account on the Mikrotik router when the balance is exhausted. | --- ## Important notes > **Warning:** This module works only as a **server module** (Products/Services). It cannot be used as an add-on product. Attempting to use it with add-on products will result in an error message. > **Post-paid traffic billing (v3.0+):** The module no longer exposes its own traffic package selector. Traffic consumption is reported back to WHMCS using standard metrics, so you can build any post-paid traffic pricing model directly in the WHMCS product configuration. > **Opposite upload/download values on Mikrotik:** the module intentionally registers opposite values on the router compared to the WHMCS settings, because Mikrotik measures incoming traffic while VPN clients experience outgoing traffic. --- ## Screenshots ![Product configuration settings](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-5u1bnbmf.png) *09-product-configuration.png* ![Product configuration — module settings area](https://doc.puq.info/uploads/images/gallery/2026-04/embedded-image-grrojxvj.png) *17-product-configuration-2.png*