mirror of
https://github.com/IdalecioSch/WGDashboard-WHMCS.git
synced 2026-07-27 16:25:49 -03:00
iTakinn
196 lines
4.7 KiB
Markdown
196 lines
4.7 KiB
Markdown
# WGDashboard WHMCS Module
|
|
|
|
WHMCS module for integration with [WGDashboard](https://github.com/donaldzou/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
|
|
|
|
```json
|
|
{
|
|
"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](https://github.com/donaldzou/WGDashboard)
|
|
- [WHMCS Developer Documentation](https://developers.whmcs.com/)
|
|
- [WireGuard Official Site](https://www.wireguard.com/)
|
|
|
|
## 📋 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
|
|
|
|
---
|