# Installation and Configuration Guide Step-by-step instructions for installing the module, preparing the Mikrotik router, and configuring WHMCS products and servers. # WHMCS Setup (Install / Update) ### Mikrotik WireGuard VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-module-mikrotik-wireguard-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/) | [FAQ](https://community.puqcloud.com/) ## System Requirements | Requirement | Minimum | |-------------|---------| | **WHMCS** | 9.x+ | | **PHP** | 8.2+ | | **ionCube Loader** | v13 or newer (v14, v15) | --- ## Download Download the latest version of the module: ```bash wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/php82/PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip ``` Unzip the archive: ```bash unzip PUQ_WHMCS-Mikrotik-WireGuard-VPN-latest.zip ``` --- ## Installation **Step 1.** Download and unzip the module archive (see above). **Step 2.** Copy the `puqMikrotikWireGuardVPN` directory to your WHMCS installation: ``` WHMCS_WEB_DIR/modules/servers/puqMikrotikWireGuardVPN ``` The resulting directory structure should look like: ``` modules/ servers/ puqMikrotikWireGuardVPN/ puqMikrotikWireGuardVPN.php hooks.php lib/ templates/ lang/ ... ``` **Step 3.** The module is ready to use. Proceed to configure a server and product in WHMCS. --- ## Update The update process is identical to the installation — simply download the latest version and replace the existing `puqMikrotikWireGuardVPN` directory. > **Note:** When updating from v2.x to v3.x, product reconfiguration is required due to the new settings storage format. --- ## Legacy Versions For older WHMCS versions (8.x), legacy module builds are available: - **All versions:** [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/) - **PHP 7.4:** [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/php74/) - **PHP 8.1:** [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/php81/) # Setup Guide: Mikrotik Preparation and Configuration ### Mikrotik WireGuard VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-module-mikrotik-wireguard-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/) | [FAQ](https://community.puqcloud.com/) ## 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: 1. Navigate to **WireGuard** section 2. Click **Add New** (+) 3. Set the interface name (e.g., `wireguard1`) 4. Set the **Listen Port** (e.g., `13231`) 5. Enable the interface ![Mikrotik WireGuard server setup](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-ty1fb9x0.png) *WireGuard interface configuration in Mikrotik WebFig* --- ## 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](../03-installation-and-configuration/03-add-server.md). # Add Server (Router Mikrotik) in WHMCS ### Mikrotik WireGuard VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-module-mikrotik-wireguard-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/) | [FAQ](https://community.puqcloud.com/) Navigate to **System Settings > Servers > Add New Server** in WHMCS admin area. --- ## 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 - Assigned IP Addresses](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-vfs3ps6b.png) *Enter the list of IP addresses for VPN clients* --- ## Step 3: Server Details 1. Select the **"PUQ Mikrotik WireGuard VPN"** module from the Module dropdown 2. Enter the correct **username** and **password** for the Mikrotik router 3. Set the **port** (default: `443` for HTTPS REST API) 4. Check the **Secure** checkbox if using HTTPS (recommended) ![WHMCS Server Details](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-aq2ogr5g.png) *Server connection settings with module selection* --- ## 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](../03-installation-and-configuration/04-product-configuration.md). # Product Configuration in WHMCS ### Mikrotik WireGuard VPN module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-module-mikrotik-wireguard-vpn) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-WireGuard-VPN/) | [FAQ](https://community.puqcloud.com/) Navigate to **System Settings > Products/Services > Create a New Product** in WHMCS admin area. Select the **"PUQ Mikrotik WireGuard VPN"** module on the **Module Settings** tab. ![Product Configuration](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-zjsclw1e.png) *Product module settings with all configuration panels* --- ## License Key Enter a valid, pre-purchased license key for the module. The license status is displayed below the key field. --- ## Mikrotik & Bandwidth | Field | Description | Default | |-------|-------------|---------| | **WireGuard Interface** | Name of the WireGuard interface on the Mikrotik router (must be pre-created) | `wireguard1` | | **Comment prefix** | Prefix added to VPN peer and queue comments on Mikrotik | `whmcs` | | **Upload (Mbs/s)** | Upload bandwidth speed limit in Mbps | `1` | | **Download (Mbs/s)** | Download bandwidth speed limit in Mbps | `1` | --- ## WireGuard Configuration These settings are included in the WireGuard client configuration file provided to customers: | Field | Description | Default | |-------|-------------|---------| | **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 (15/25/30/60/120 seconds) | `25 seconds` | **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) --- ## History | Field | Description | Default | |-------|-------------|---------| | **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` | --- ## Client Area | Field | Description | Default | |-------|-------------|---------| | **Link to instruction** | URL to setup instructions (displayed in client area as "User manual" button) | Empty | | **Link to VPN clients** | URL to WireGuard client downloads page (displayed as "VPN client" button) | Empty | **Recommended:** Set "Link to VPN clients" to `https://www.wireguard.com/install/` — the official WireGuard client downloads page. --- ## 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](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-1e9q76px.png) *Metric Billing settings with Download and Upload metrics enabled*