EZSCALE/virtfusion-whmcs-module
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Enhance VirtFusion WHMCS module with security fixes, new features, and improved UX

Browse Source 
Security improvements:
- Enable SSL/TLS certificate verification by default (was disabled, MITM risk)
- Remove error_reporting(0) that silenced all errors
- Add input sanitization on all user parameters (int casting, regex filtering)
- Return proper HTTP status codes (401, 403, 400, 500) instead of always 200
- Add XSS protection with htmlspecialchars and encodeURIComponent
- Add null checks on API response data before property access

New features:
- Power management: boot, shutdown, restart, and force power off controls
- Server rebuild: reinstall with any available OS template from client area
- Server rename: change server display name via PATCH API
- OS template fetching: client-side endpoint for rebuild OS selection
- TestConnection: validate API credentials from WHMCS server settings
- ServiceSingleSignOn: native WHMCS SSO integration for VirtFusion panel
- Server status badge: visual indicator of server state in overview
- Traffic usage display: show bandwidth used vs allocated
- Checkout validation: ShoppingCartValidateCheckout hook ensures OS selection

Ordering process improvements:
- Add default "Select Operating System" placeholder option
- Add "No SSH Key (Optional)" default for SSH dropdown
- Hide SSH key field/container when no keys available
- Wrap hook in try/catch to prevent checkout page breakage
- Sanitize template names with htmlspecialchars
- Use JSON_HEX_* flags for safe script injection

Theme compatibility:
- Properly formatted Smarty templates with readable indentation
- Dual panel/card CSS classes for Bootstrap 3/4/5 compatibility
- Responsive power button layout with mobile breakpoint
- Framework-agnostic HTML that works with Six, Twenty-One, Lagom, and custom themes
- Suspended service state messaging

Code quality:
- Readable, unminified JavaScript with JSDoc header
- Structured CSS with logical section organization
- Improved error messages throughout all provisioning functions
- Added PATCH method support to Curl wrapper
- Added curl error capture on connection failures
- Added connection and request timeouts (10s/30s)
- Fixed memory conversion to check key name instead of display name

Documentation:
- Complete README rewrite with installation, configuration, and troubleshooting guides
- API endpoint reference table
- Configurable options mapping documentation
- Theme override instructions
- Security considerations section

https://claude.ai/code/session_01TCsJ4WZCGuEX3zqh1tQ2zx
This commit is contained in:
Claude
2026-02-07 12:18:11 +00:00
parent 7b87fdcc3f
commit c93072b1c6
12 changed files with 1468 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
README.md
View File

@@ -5,34 +5,194 @@
![GitHub issues](https://img.shields.io/github/issues/EZSCALE/virtfusion-whmcs-module)
![GitHub pull requests](https://img.shields.io/github/issues-pr/EZSCALE/virtfusion-whmcs-module)
This module requires VirtFusion v1.7.3 or higher as this is what it's based on. Please refer to the
official [documentation](https://docs.virtfusion.com/integrations/whmcs).
A comprehensive WHMCS provisioning module for [VirtFusion](https://virtfusion.com) that enables automated VPS server provisioning, management, and client self-service directly from WHMCS.
## Requirements
- **VirtFusion** v1.7.3 or higher
- **WHMCS** 8.x or higher
- **PHP** 8.0 or higher
- A valid VirtFusion API token with appropriate permissions
## Features
### Provisioning
- Automatic server creation, suspension, unsuspension, and termination
- Package/plan upgrades and downgrades
- Automatic VirtFusion user creation linked to WHMCS client accounts
- Configurable options mapping for dynamic resource allocation
### Client Area
- **Server Overview** - Real-time server information (hostname, IP, resources, status badge)
- **Power Management** - Start, restart, shutdown, and force power off controls
- **Control Panel SSO** - One-click login to VirtFusion panel via authentication tokens
- **Server Rebuild** - Reinstall with any available OS template directly from WHMCS
- **Password Reset** - Reset VirtFusion panel login credentials
- **Bandwidth Usage** - Traffic usage display with allocation limits
- **Billing Overview** - Product, billing cycle, and payment information
### Admin Area
- Server connection testing (Test Connection button)
- Server information display with live data from VirtFusion
- Admin impersonation for VirtFusion panel access
- Editable Server ID field for manual adjustments
- Full server object JSON viewer
### Ordering Process
- Dynamic OS template dropdown populated from VirtFusion API
- SSH key selection dropdown for users with saved keys
- Checkout validation ensuring OS selection before order placement
- Compatible with all WHMCS order form templates
### Theme Compatibility
- Works with **all WHMCS themes** including Six, Twenty-One, Lagom, and custom themes
- Uses dual `panel`/`card` CSS classes for Bootstrap 3/4/5 compatibility
- Framework-agnostic HTML structure
- Responsive design with mobile-friendly layouts
- Templates support the WHMCS theme override system
### Security
- SSL/TLS certificate verification enabled by default
- Input sanitization on all user-supplied parameters
- Service ownership validation on all client API endpoints
- Proper HTTP status codes for error responses (401, 403, 400, 500)
- XSS protection via `htmlspecialchars()` and `encodeURIComponent()`
- Direct file access prevention on all PHP files
## Installation
1. Download the latest release from the [releases](https://github.com/EZSCALE/virtfusion-whmcs-module/releases) page.
2. Extract the contents of the archive and upload the modules folder to your WHMCS installation directory.
2. Extract the archive and upload the `modules/` folder to your WHMCS installation directory.
3. In WHMCS Admin, go to **Configuration > System Settings > Servers** and add a new server:
- **Type**: VirtFusion Direct Provisioning
- **Hostname**: Your VirtFusion panel hostname (e.g., `cp.example.com`)
- **Password/Access Hash**: Your VirtFusion API token
4. Click **Test Connection** to verify the API connection.
5. Create or edit a product and set the **Module** to "VirtFusion Direct Provisioning".
## :heavy_exclamation_mark: Important Notes :heavy_exclamation_mark:
## Custom Fields Setup
You must create two custom fields in WHMCS for this module to work. You need to configure the following custom fields on
each product you want to use this module with.
You **must** create two custom fields on each product that uses this module:
| Field Name | Field Type | Description | Validation | Select Options | Admin Only | Required Field | Show on Order Form | Show on Invoice |
|--------------------------|------------|--------------------------|-------------|----------------|------------|----------------|--------------------|-----------------|
| Initial Operating System | Text Box | Set to whatever you want | Leave Blank | Leave Blank | :x: | :x: | :white_check_mark: | :x: |
| Initial SSH Key | Text Box | Set to whatever you want | Leave Blank | Leave Blank | :x: | :x: | :white_check_mark: | :x: |
| Field Name | Field Type | Show on Order Form | Admin Only | Required |
|--------------------------|------------|--------------------| ---------- | -------- |
| Initial Operating System | Text Box | Yes | No | No |
| Initial SSH Key | Text Box | Yes | No | No |
You can run this SQL query to create the custom fields. Run the SQL from this [file](modify.sql) or copy the contents
from it.
You can run the included SQL to auto-create these fields for all VirtFusion products:
## What does this module change?
```sql
-- See modify.sql for the complete query
```
This module changes the following things:
Or run the SQL from the [modify.sql](modify.sql) file.
- Adds configurable options to the product configuration page to allow the user to select the operating system and add
an ssh key to the initial deployment.
## Module Configuration Options
## TODO
Each product using this module has three configuration options:
- [ ] Add post checkout checks to ensure the user has selected an operating system and added a ssh key.
| Option | Name | Description |
|--------|------|-------------|
| Config Option 1 | Hypervisor Group ID | The VirtFusion hypervisor group ID for server placement (default: 1) |
| Config Option 2 | Package ID | The VirtFusion package ID that defines server resources (default: 1) |
| Config Option 3 | Default IPv4 | Number of IPv4 addresses to assign (0-10, default: 1) |
## Configurable Options (Dynamic Pricing)
To allow customers to select different resource levels with pricing, create WHMCS Configurable Options groups with these option names:
| VirtFusion Parameter | Default Option Name | Description |
|---------------------|--------------------| ----------- |
| `packageId` | Package | VirtFusion package ID |
| `hypervisorId` | Location | Hypervisor group for server placement |
| `ipv4` | IPv4 | Number of IPv4 addresses |
| `storage` | Storage | Disk space in GB |
| `memory` | Memory | RAM in MB (values < 1024 auto-converted from GB) |
| `traffic` | Bandwidth | Monthly traffic allowance in GB |
| `cpuCores` | CPU Cores | Number of CPU cores |
| `networkSpeedInbound` | Inbound Network Speed | Inbound speed in Mbps |
| `networkSpeedOutbound` | Outbound Network Speed | Outbound speed in Mbps |
| `networkProfile` | Network Type | VirtFusion network profile ID |
| `storageProfile` | Storage Type | VirtFusion storage profile ID |
### Custom Option Name Mapping
If your configurable option names differ from the defaults, create a mapping file:
1. Copy `config/ConfigOptionMapping-example.php` to `config/ConfigOptionMapping.php`
2. Edit the mapping array to match your option names
## Theme Override
To customize the module templates for a specific theme, copy the template files to:
```
/templates/yourthemename/modules/servers/VirtFusionDirect/
```
WHMCS will automatically use theme-specific templates when available.
## API Endpoints Used
This module uses the following VirtFusion API v1 endpoints:
| Endpoint | Purpose |
|----------|---------|
| `GET /connect` | Connection testing |
| `GET/POST /users` | User lookup and creation |
| `POST /servers` | Server creation |
| `POST /servers/{id}/build` | OS installation |
| `GET /servers/{id}` | Server details retrieval |
| `DELETE /servers/{id}` | Server termination |
| `POST /servers/{id}/suspend` | Server suspension |
| `POST /servers/{id}/unsuspend` | Server unsuspension |
| `PUT /servers/{id}/package/{pkgId}` | Package changes |
| `POST /servers/{id}/power/*` | Power management (boot/shutdown/restart/poweroff) |
| `PATCH /servers/{id}/name` | Server renaming |
| `POST /users/{id}/serverAuthenticationTokens/{serverId}` | SSO token generation |
| `POST /users/{id}/byExtRelation/resetPassword` | Password reset |
| `GET /packages` | Package listing |
| `GET /media/templates/fromServerPackageSpec/{id}` | OS template listing |
| `GET /ssh_keys/user/{id}` | SSH key listing |
## Troubleshooting
### Connection Test Fails
- Verify the VirtFusion panel hostname is correct and accessible
- Ensure the API token has not expired
- Check that SSL certificates on the VirtFusion panel are valid (self-signed certificates will cause connection failures)
### Server Creation Fails
- Check the Module Log in WHMCS Admin (Utilities > Logs > Module Log) for detailed error messages
- Verify the Package ID and Hypervisor Group ID are correct
- Ensure the VirtFusion API token has permission to create servers
### OS Templates Not Showing
- Confirm the Package ID (Config Option 2) is set correctly
- Verify the package has OS templates assigned in VirtFusion
- Check that the "Initial Operating System" custom field exists on the product
### Client Area Shows Error
- Ensure a VirtFusion server is configured in WHMCS Server Settings
- Check that the service has been provisioned (not in Pending status)
- Review the Module Log for API communication errors
### SSO / Control Panel Login Fails
- The VirtFusion panel must be accessible from the client's browser
- Verify the VirtFusion user exists (check by external relation ID)
- Ensure authentication token generation permissions are enabled on the API token
## Security Considerations
- **API Tokens**: Store API tokens only in the WHMCS server password field. WHMCS encrypts this value at rest.
- **SSL Verification**: SSL certificate verification is enabled by default. Do not disable it in production environments.
- **Module Updates**: Keep the module updated to receive security patches.
- **Access Control**: The module validates service ownership on every client API call. Admin endpoints require WHMCS admin authentication.
## Contributing
Contributions are welcome. Please open an issue or pull request on the [GitHub repository](https://github.com/EZSCALE/virtfusion-whmcs-module).
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE.md](LICENSE.md) file for details.