WHMCS Module v3
From SolusVM
Overview
This module is an addon for the popular WHMCS billing solution. The module allows you to create, destroy, suspend, unsuspend, upgrade, downgrade, reboot, boot and shutdown virtual servers, plus functions to provision virtual servers in different locations, all directly from within WHMCS.
The client also has an array of functions and statistics from within the client area, including, reboot, boot, shutdown, change passwords, change hostname, view resource usage and graphs, plus the added bonus of a serial console or VNC. A full overview is on the whmcs wiki here
The module supports SSL mode as default with or without a valid certificate on the SolusVM master.
Installation
Requirements
- SolusVM Master
- WHMCS Version 4.4.2 or higher
- IonCude Loaders
- WHMCS template that uses jquery. All default WHMCS templates use jquery as default.
- Max VPS, Max Memory and Max Disk Space set correctly under the node settings
Download
Version 3.2 Stable (2011/12/08)
Release Notes
- Fixed client area graphs showing off center in WHMCS version 5.
- Added nodeid custom field to each product. The nodeid is returned and stored in this custom field for each virtual server created. This is optional. (SolusVM version 1.9 and above).
Version 3.1 Stable (2011/09/20)
Release Notes
- Added Control Panel Chooser for automatic BuycPanel activation Control Panel Chooser
- Added new hash variable to disable removing IP from terminated product
Upload
Once you have downloaded the <module>.zip file to your computer you need to extract the files using your favorite zip extraction program.
Now you should be presented with a folder called Module. You need to upload the contents of the Module folder to the root of your WHMCS installation.
Upgrading from version 2
If you are upgrading from version 2 (solusvmpro), this module should just drop in place of the old module, however if you use the Operating System Selector configurable option you will need to rename the configurable options before they will work with the new module. Please see the section on configurable options below.
Configuration
Creating API Users in SolusVM
To create an API user in SolusVM click Configuration >> API Users >> Create API User.
You will be presented with some fields like the image below:
The ID & Key are auto generated and cannot be changed, all you need to add is the IP address of your WHMCS installation and set it to active.
Adding a Master to WHMCS
Before you can configure your products to use the SolusVM module you need to add a master server to WHMCS.
In WHMCS select Setup >> Servers >> Add new server
Fill in the form as illustrated in the images below.
Don't forget to tick Secure for SSL connections (You should use this when possible)
Now click Save Changes to add the master to WHMCS.
Creating a Product
In WHMCS select Setup >> Products/Services
Now click Create a New Product and fill in the form as illustrated in the image below.
Click Continue.
Now fill in all your product details. After that you need to click on Module Setting and select Solusvm from the dropdown menu.
Once the module has loaded you will be presented with the follow options as illustrated in the image below.
NOTE: When there isn't listed anything in the select boxes, select the virtualization type and click on the save button. After that you will see the select boxes filled.
First of all you need to select the master server you created in section 3.3 #Adding a Master to WHMCS then click Save Changes to load all the templates, plans and servers directly from the SolusVM master.
Once the page has reloaded you can set all the options you need for this product.
Options Explained
Module User Type : If you are an admin or reseller (Currently only Admin supported, Non beta versions will have this function)
Default Node : The node the virtual server will be built on if no overide is given
Master Server : The master server this package is assigned to
Default Plan : Then plan on the master the package is assigned to
Virtualization Type : Choose either OpenVZ, Xen-PV, Xen-HVM or KVM
Default Operating System : The operating system that is used if not defined in configurable options.
Username Prefix : This is the unique prefix that defines the username for each client. Set this the same in all plans. i.e: vmuser
IP Addresses : The amount of ip addresses for this package
Node Group : The node group this product should be built on (This will override the default node)
Click Save Changes then select the Custom Fields tab.
This is the important part! You need to create 3 custom fields:
Field Name: vserverid , Field Type: Text Box and tick Admin Only. Field Name: consoleusername , Field Type: Text Box and tick Admin Only. Field Name: consolepassword , Field Type: Text Box and tick Admin Only.
Make sure it looks like this image below.
The vserverid custom field will hold the unique vserverid that is used within SolusVM.
OPTIONAL: You can also create a custom field to store the node id the virtual server is created on. The custom field must be called 'nodeid'
When you have set the custom fields, click Save Changes.
Thats it! the basic configuration is complete.
Optional Configuration
Client Operating System Chooser
This handy little feature lets you add a dropdown list of operating systems on the products order form allowing the client to choose the operating system they want without having to rebuild there vps after its been setup with the default template.
To set this up you need to create a configurable option group for each virtualization type:
You then need to add a new configurable option to the new group. The default name for the configurable option is 'Operating System', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your templates with a friendly name and filename.
The first part is the filename i.e fedora-9-x86 and the second part is the friendly name i.e Fedora 9 32 Bit. Both parts must be seperated with a |
The filename must match the filename of the template or ISO as shown in SolusVM i.e fedora-9-x86.tar.gz needs to be listed as fedora-9-x86 or windows-7-x86.iso must be windows-7-x86, so the rule is just remove the .tar.gz or .iso when listing them in WHMCS.
Heres an image of what the options should look like.
Thats it, just click Save Changes and follow this procedure for each virtualization type you need.
Group Chooser
The group chooser lets you add a dropdown list of definable node groups on the products order form allowing the client to choose a specific group on order. This can be handy for a serveral purposes including a location chooser.
For example, to set up a Location Chooser:
Create a new configurable option group like in the image below
You then need to add a new configurable option to the new group. The default name for the configurable option is 'Location', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your locations with a friendly name and the node group id (You can get the id's from the node group list in SolusVM).
Example:
Thats it, just click Save Changes!.
Control Panel Chooser
The control panel chooser allows you add a dropdown list of definable control panels on the products order form allowing the client to choose a control panel on order. This feature on supports auto activation using BuycPanel.
Create a new configurable option group like in the image below
You then need to add a new configurable option to the new group. The default name for the configurable option is 'Control Panel', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your locations with a friendly name and the control panel license id (cPanel Monthly is ID 1 & cPanel Yearly is ID 2).
Example:
Thats it, just click Save Changes!.
Resource Chooser
The resource chooser allows your clients to order custom configurations of virtual servers. The resource chooser allows memory, disk space, bandwidth, cpu cores and extra ip addresses to be defined within set of configurable options for the client to choose on order.
For example, to set up a Resource Chooser:
Create a new configurable option group like in the image below
You then need to add a new configurable option to the new group. The default name for the memory configurable option is 'Memory', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your variables with a friendly name and the amount of memory in MEGABYTES. The format is MEGABYTES|DESCRIPTION HERE
Example:
The default name for the disk space configurable option is 'Disk Space', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your variables with a friendly name and the amount of disk space in GIGABYTES. The format is GIGABYTES|DESCRIPTION HERE
Example:
The default name for the bandwidth configurable option is 'Bandwidth', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your variables with a friendly name and the amount of bandwidth in GIGABYTES. The format is GIGABYTES|DESCRIPTION HERE
Example:
The default name for the cpu configurable option is 'CPU', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your variables with a friendly name and the amount of cpu cores in CORES. The format is CORES|DESCRIPTION HERE
Example:
The default name for the extra ip address configurable option is 'Extra IP Address', however this can be changed to a custom name using the correct hash variable.
Select Option Type: Dropdown.
In Field Options you need to define your variables with a friendly name and the amount of extra ips in AMOUNT. The format is AMOUNT|DESCRIPTION HERE
Example:
Once you have configured the options, the product order form will look something like the screenshot below:
Global Options (Hash Variables)
You can override several different options of the module by setting parameters in the master server access hash field. All the options are listed below:
| Resource Selector | ||
|---|---|---|
| Variable | Value | Description |
| <custom-config-memory>value</custom-config-memory> | Numeric | Name of resource selector configurable option for memory. If unspecified default is Memory |
| <custom-config-diskspace>value</custom-config-diskspace> | Numeric | Name of resource selector configurable option for disk space. If unspecified default is Disk Space |
| <custom-config-bandwidth>value</custom-config-bandwidth> | Numeric | Name of resource selector configurable option for bandwidth. If unspecified default is Bandwidth |
| <custom-config-cpu>value</custom-config-cpu> | Numeric | Name of resource selector configurable option for cpu cores. If unspecified default is CPU |
| <custom-config-extraip>value</custom-config-extraip> | Numeric | Name of resource selector configurable option for extra ips. If unspecified default is Extra IP Address |
| Operating System Selector | ||
| Variable | Value | Description |
| <openvz-os-selector-name>value</openvz-os-selector-name> | Text String | Name of operating system selector configurable option for OpenVZ. If unspecified default is Operating System |
| <xenpv-os-selector-name>value</xenpv-os-selector-name> | Text String | Name of operating system selector configurable option for Xen PV. If unspecified default is Operating System |
| <xenhvm-os-selector-name>value</xenhvm-os-selector-name> | Text String | Name of operating system selector configurable option for Xen HVM. If unspecified default is Operating System |
| <kvm-os-selector-name>value</kvm-os-selector-name> | Text String | Name of operating system selector configurable option for KVM. If unspecified default is Operating System |
| Group Selector | ||
| Variable | Value | Description |
| <openvz-group-selector-name>value</openvz-group-selector-name> | Text String | Name of group selector configurable option for OpenVZ. If unspecified default is Location |
| <xenpv-group-selector-name>value</xenpv-group-selector-name> | Text String | Name of group selector configurable option for Xen PV. If unspecified default is Location |
| <xenhvm-group-selector-name>value</xenhvm-group-selector-name> | Text String | Name of group selector configurable option for Xen HVM. If unspecified default is Location |
| <kvm-group-selector-name>value</kvm-group-selector-name> | Text String | Name of group selector configurable option for KVM. If unspecified default is Location |
| Control Panel Selector | ||
| Variable | Value | Description |
| <control-panel-selector-name>value</control-panel-selector-name> | Text String | Name of control panel selector configurable option. If unspecified default is Control Panel |
| Default Product Override | ||
| Variable | Value | Description |
| <default-openvz-node>value</default-openvz-node> | Text String | This will overide the server any OpenVZ vps are created on. VALUE must be the name of the server as listed in SolusVM |
| <default-xen-node>value</default-xen-node> | Text String | This will overide the server any Xen PV vps are created on. VALUE must be the name of the server as listed in SolusVM |
| <default-hvm-node>value</default-hvm-node> | Text String | This will overide the server any Xen HVM vps are created on. VALUE must be the name of the server as listed in SolusVM |
| <default-kvm-node>value</default-kvm-node> | Text String | This will overide the server any KVM vps are created on. VALUE must be the name of the server as listed in SolusVM |
| General | ||
| Variable | Value | Description |
| <debug>value</debug> | on|off | This will give you debug output to screen when you run a module function. Only switch this on when you are testing, allways turn it off when you have finished with it |
| <port>value</port> | numeric port number | This will force the module to talk to the master on a custom port |
| <username-prefix>value</username-prefix> | String | Enter a default username prefix for the client login to solusvm. i.e: vmuser , When a client has multiple vps they will be created under the same account |
| <default-hostname>value</default-hostname> | Hostname | Specify a default hostname if no hostname is specified on order. i.e: vps.server.com. If not specified, vps.server.com will be used |
| <connect-timeout>value</connect-timeout> | Number | Specify a custom connection timout for the api (optional) |
| <connect-data-timeout>value</connect-data-timeout> | Number | Specify a custom data connection timout for the api (optional) |
| <admin-control>value</admin-control> | enable|disable | Enable/Disable the admin area controls. Default is enabled. |
| <admin-control-type>value</admin-control-type> | onload|ondemand | Show admin control on page load or on demand. Default is onload. |
| <controlpanelbutton-admin>value</controlpanelbutton-admin> | url to admincp | Button that links to admincp. Button will now show if left unspecified. |
| <removeip-terminated-product>value</removeip-terminated-product> | yes|no | Remove ip's from terminated products. Default is yes. |
| Client Area | ||
| Variable | Value | Description |
| <serialconsole>value</serialconsole> | enable|disable | Enable/Disable the clientarea serial console. Default is enable |
| <vnc>value</vnc> | enable|disable | Enable/Disable the clientarea vnc. Default is enable |
| <consolepassword>value</consolepassword> | enable|disable | Enable/Disable the clientarea change console password function. Default is enable |
| <vncpassword>value</vncpassword> | enable|disable | Enable/Disable the clientarea change vnc password function. Default is enable |
| <rootpassword>value</rootpassword> | enable|disable | Enable/Disable the clientarea change root password function. Default is enable |
| <hostname>value</hostname> | enable|disable | Enable/Disable the clientarea change hostname function. Default is enable |
| <reboot>value</reboot> | enable|disable | Enable/Disable the clientarea reboot button. Default is enable |
| <boot>value</boot> | enable|disable | Enable/Disable the clientarea boot button. Default is enable |
| <shutdown>value</shutdown> | enable|disable | Enable/Disable the clientarea shutdown button. Default is enable |
| <graphs>value</graphs> | enable|disable | Enable/Disable displaying graphs in the client area. Default is enable |
| <vstatus>value</vstatus> | enable|disable | Enable/Disable displaying the virtual server status in the client area. Default is enable |
| <iplist>value</iplist> | enable|disable | Enable/Disable displaying the list of ipaddresses in the client area. Default is enable |
| <memusage>value</memusage> | enable|disable | Enable/Disable displaying the virtual server memory usage. Default is enable |
| <diskusage>value</diskusage> | enable|disable | Enable/Disable displaying the virtual server disk usage. Default is enable |
| <bwusage>value</bwusage> | enable|disable | Enable/Disable displaying the virtual server bandwidth usage. Default is enable |
| <controlpanelbutton>value</controlpanelbutton> | Link to control panel | Add a login to control panel button to the clientarea controls. Unless specified, this feature is disabled |
| <clientfunctions>value</clientfunctions> | enable|disable | Enable/Disable all the client functions. Default is enable |
Custom Configuration
Custom configuration is done via a custom configuration file (custom.php). To use custom configurations you need need to rename custom-example.php in the module folder (modules/servers/solusvmpro/) to custom.php
Client Area
To customise the look & layout of the client area, you need to uncomment the following functions:
solusvmpro_customclientarea() solusvmpro_customclientareaunavailable()
Hostname
This function allows you to manipulate the hostname of the virtual server before it is created. Uncomment the following function:
solusvmpro_hostname()
Username
This function allows you to manipulate the username of the client before it is created. Uncomment the following function:
solusvmpro_username()
Admin Link
This function allows you to display a button in the server list in WHMCS to directly login to you master. Uncomment the following function:
solusvmpro_AdminLink()
Module Create Step 1
This function runs before any other code in the module and before the virtual server is created. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_create_one()
- available in beta 3 and above
Module Create Step 2
This function runs just before the client is created and before the virtual server is created. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_create_two()
- available in beta 3 and above
Module Create Step 3
This function runs just before the virtual server is created. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_create_three()
- available in beta 3 and above
Module Create Step 4
This function runs if the virtual server has been created successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_create_four()
- available in beta 3 and above
Module Create Step 5
This function runs if the virtual server has NOT been created successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_create_five()
- available in beta 3 and above
Module Terminate Pre
This function runs before any code in the terminate function runs. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_terminate_pre()
- available in beta 3 and above
Module Terminate Post Success
This function runs if the virtual server has been terminated successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_terminate_post_success()
- available in beta 3 and above
Module Terminate Post Error
This function runs if the virtual server has NOT been termainted successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_terminate_post_error()
- available in beta 3 and above
Module Suspend Pre
This function runs before any code in the suspend function runs. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_suspend_pre()
- available in beta 3 and above
Module Suspend Post Success
This function runs if the virtual server has been suspended successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_suspend_post_success()
- available in beta 3 and above
Module Suspend Post Error
This function runs if the virtual server has NOT been suspended successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_suspend_post_error()
- available in beta 3 and above
Module UnSuspend Pre
This function runs before any code in the unsuspend function runs. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_unsuspend_pre()
- available in beta 3 and above
Module UnSuspend Post Success
This function runs if the virtual server has been unsuspended successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_unsuspend_post_success()
- available in beta 3 and above
Module UnSuspend Post Error
This function runs if the virtual server has NOT been unsuspended successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_unsuspend_post_error()
- available in beta 3 and above
Module Change Package Pre
This function runs before any code in the change package function runs. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_changepackage_pre()
- available in beta 3 and above
Module Change Package Post Success
This function runs if the package has been changed successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_changepackage_post_success()
- available in beta 3 and above
Module Change Package Post Error
This function runs if the package has NOT been changed successfully. All standard WHMCS variables are passed to this function. Uncomment the following function:
solusvmpro_changepackage_post_error()
- available in beta 3 and above
Debug Mode
To enable debug mode on the module you need to add the following variable to the server hash field setting in WHMCS under your master server
<debug>on</debug>
One it's enable it will display output for each action on the screen. Always disable debug mode once you have finished using it!!
<debug>off</debug>
