EZSCALE/virtfusion-whmcs-module
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity
Files
c93072b1c6e90ba0bac4c1495860fb1aefb856f5
virtfusion-whmcs-module/README.md
Claude c93072b1c6 Enhance VirtFusion WHMCS module with security fixes, new features, and improved UX 
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
2026-02-07 12:18:11 +00:00

199 lines
8.9 KiB
Markdown
Raw Blame History

# VirtFusion Direct Provisioning Module for WHMCS
[![GitHub Super-Linter](https://github.com/EZSCALE/virtfusion-whmcs-module/actions/workflows/publish-release.yml/badge.svg)](https://github.com/EZSCALE/virtfusion-whmcs-module/actions)
![GitHub](https://img.shields.io/github/license/EZSCALE/virtfusion-whmcs-module)
![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)
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 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".
## 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:
```sql
-- See modify.sql for the complete query
```
Or run the SQL from the [modify.sql](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:
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.
Reference in New Issue View Git Blame Copy Permalink