c93072b1c6
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
VirtFusion Direct Provisioning Module for WHMCS
A comprehensive WHMCS provisioning module for VirtFusion 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/cardCSS 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()andencodeURIComponent() - Direct file access prevention on all PHP files
Installation
- Download the latest release from the releases page.
- Extract the archive and upload the
modules/folder to your WHMCS installation directory. - 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
- Click Test Connection to verify the API connection.
- Create or edit a product and set the Module to "VirtFusion Direct Provisioning".
Custom Fields Setup
You must create two custom fields on each product that uses this module:
| 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 the included SQL to auto-create these fields for all VirtFusion products:
-- See modify.sql for the complete query
Or run the SQL from the modify.sql file.
Module Configuration Options
Each product using this module has three configuration options:
| 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:
- Copy
config/ConfigOptionMapping-example.phptoconfig/ConfigOptionMapping.php - 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.
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.