WGDashboard-WHMCS/README.md

WGDashboard WHMCS Module

WHMCS module for integration with WGDashboard, enabling automated WireGuard peer management through WHMCS.

📋 Requirements

• WHMCS 7.0 or higher
• WGDashboard v4.0+ with API enabled
• PHP 7.4 or higher
• PHP cURL extension enabled

🚀 Installation

1. Upload the module files to the WHMCS directory:

   /modules/servers/wgdashboard/
   

2. File structure:

   modules/server/wgdashboard/
   ├── wgdashboard.php
   └── clientarea.tpl
   

3. In the WHMCS admin panel, navigate to: Setup → Products/Services → Servers → Add New Server

4. Configure the server:

   • Hostname: IP or domain of WGDashboard (e.g., 10.0.238.222 or vpn.example.com)
   • Module: WGDashboard
   • Port: API port (e.g., 10086)
   • Password: WGDashboard API Key

5. Click Test Connection to validate the configuration.

⚙️ Product Configuration

1. Create or edit a product in Setup → Products/Services

2. In the Module Settings tab:

   • Module Name: WGDashboard
   • Server Group: Select the configured server

3. Configuration Options:

   • Allowed IPs: Allowed IPs for the peer (default: 0.0.0.0/0)
   • Config Name: WireGuard configuration name in the dashboard (default: wg0)
   • Peer Template: (Optional) JSON template to customize peer creation

Peer Template Example

{
  "DNS": "8.8.8.8,1.1.1.1",
  "mtu": 1420,
  "keepalive": 25
}

Available placeholders:

• {{client_email}} - Client's email
• {{domain}} - Service domain
• {{serviceid}} - Service ID in WHMCS

🔧 Features

Peer Automation

Module options:

• ✅ Creation: Automatically generates keys and creates peer in WGDashboard
• ✅ Suspension: Restricts peer access when service is suspended
• ✅ Reactivation: Restores access when service is reactivated
• ✅ Termination: Completely removes peer when service is cancelled

Client Area

Client Area:

• 📱 QR Code: For quick configuration on mobile devices
• 📄 Formatted Configuration: Ready-to-use WireGuard configuration file
• 📋 Download: Button to download .conf file

Admin Panel

In the client's service tab, the administrator views:

• Public Key: Peer's public key
• Peer Name: Peer identifier name
• Allowed IPs: Allowed IPs
• Status: Current peer state
• Latest Handshake: Last handshake with server
• Data Received: Volume of data received From peer to server
• Data Sent: Volume of data sent From server to peer

🌐 WGDashboard Configuration

To use this module, ensure the WGDashboard API is enabled:

1. Access WGDashboard settings
2. Navigate to Settings → API
3. Enable the API and generate a key
4. Use this key in the Password field of the server configuration in WHMCS

🐛 Troubleshooting

Connection Test Fails

Error 401/403: Verify API Key

Solution: Confirm that the API Key is correct in the server's Password field

Error 404: Endpoint not found

Solution: Check if your WGDashboard version supports the API

Error 500: WGDashboard internal error

Solution: Check WGDashboard logs on the server

Peer Not Created

1. Enable Module Debug Log in WHMCS
2. Navigate to Utilities → Logs → Module Log
3. Look for "WGDashboard-WHMCS" entries
4. Analyze request and response details

QR Code Doesn't Appear

Check:

• If JavaScript is enabled in the browser
• Browser console for errors (F12)
• If QRCode.js library is loading correctly

Port Not Recognized

The module uses WHMCS's Server Port field to define the API port. Do not include the port in the hostname, only in the dedicated field.

✅ Correct:

• Hostname: 10.0.0.55
• Port: 10086

❌ Incorrect:

• Hostname: 10.0.0.55:10086
• Port: (empty)

🔄 Compatibility

• WHMCS: 7.0+
• WGDashboard: v4.0+
• PHP: 7.4, 8.0, 8.1, 8.2
• WireGuard: All versions

📄 License

This module is provided "as is", without warranties of any kind.

🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a branch for your feature
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

🔗 Useful Links

• WGDashboard GitHub
• WHMCS Developer Documentation
• WireGuard Official Site

📋 Changelog

v1.0.0

• ✨ Initial release
• ✅ Peer creation, suspension, reactivation, and termination
• 📱 Client area with QR code and formatted configuration
• 🌐 Portuguese translation
• 🔐 Local WireGuard key generation
• 📊 Admin panel with peer statistics

---