Legacy WHMCS Module Documentation
For module version 2.0 (Nov 2011)Outdated: Please upgrade to the latest module instead
Content
Installation
- Place the contents of the archive you have received in your WHMCS installation directory under "modules/servers"
- Enable the Multicraft API under "Settings"-"Panel Configuration" in your Multicraft panel.
- Create an API key for a user with superuser privileges by going to the user profile and clicking on "Generate API key" in the menu to the left.
Create "Servers" Entry
The module automatically distributes Minecraft servers over multiple daemons so you only have to create one server entry per panel.Under "Setup"-"Servers", click on "Add New Server" and fill in the fields:
- Hostname
Your control panel URL (http://your.address/multicraft) - IP Address
Since every daemon has its own IP this setting is not used - Assigned IP Addresses
A list of available dedicated IPs in the format DaemonID,IP (e.g.: 3,192.168.1.1). - Type
Set this to "Multicraft" - Username
The name of the user for which you have generated the API key - Password
This is optional. You can set this to the users password to allow automatic login - Access Hash
The API key you have generated for that user (a string of the format: e5a0214fc52c94448d6a)
Under "Setup"-"Servers", click on "Create New Group" and add the server you just created to this group.
For illustration, here are the two relevant sections of the "Servers" entry:


Create Products
Create a product under "Setup"-"Products/Services". The module related settings are under "Module Settings", everything else is the same as for a standard WHMCS product entry. Please contact WHMCS support if you have any question regarding WHMCS base functionality.Module Settings
- Module Name
Set this to "Multicraft" - Server Group
Set this to the server group you created before - Minecraft Server Slots
Player slot count for the created server - Minecraft Server RAM
Memory amount in MB for the created server - JAR File, Look for JARs in, Owner Selectable JAR, Owner Changeable Servername, Owner Scheduled Tasks, Owner Managed FTP, Owner changeable visibility, Default Role, Server visible for, Start Server
Same as in the Multicraft server settings - Dedicated IP
- If available
Try to assign a dedicated IP from the "Assigned IP Addresses" list of the WHMCS "Servers" entry - No
Don't try to assign a dedicated IP - Yes
Assign a dedicated IP, fail if no IP is available
- If available
- Create FTP Account
Whether or not to create a FTP account for the user - Allowed Daemons
Restrict available daemons to the daemon IDs listed in this field (comma separated). All daemons are used if this is empty. - Max Servers per Daemon
The maximum number of servers that get created on one daemon. If a daemon has the specified amount of servers running it won't be considered for new servers - Calculate used RAM
Whether to include suspended servers when determining if a daemon has enough RAM available for the new server - Delete Worlds on Terminate
Whether to delete a servers base directory containing all the data related to this server when the WHMCS service is terminated - Enable Log Mails
- Only on Errors
Only send a log mail to the address specified below if the automatic setup failed - No
Never send log mails - Yes
Always send log mails
- Only on Errors
- Log Mail Recipient
The address to which the log mail is to be sent

Custom Fields
The module recognizes a "Custom Field" or "Configurable Option" with "Field Type" set to "Text Box" and the "Field Name" containing the string "user" (e.g. "Username", "Multicraft user", "Login Username", etc.) and will use that as the Multicraft username. If no such custom field exists the the clients email address will be used as the Multicraft username.
Usage
Selecting the Daemon by Available Memory
The module will go through all daemons and select the first one that has enough free RAM and that has less servers on it than what you set as "Max servers per daemon" in the products "Module Settings".If no such daemon is found the provisioning will fail.
In order for the module to be able to determine the maximum amount of memory available on a daemon you need to have the "totalMemory" setting configured correctly in your multicraft.conf. It must be set to the total amount of memory in MB that you wish to be assigned to Minecraft servers. Note that any changes on your multicraft.conf require the daemon to be restarted.
Dedicated IPs
Dedicated IPs are listed in the WHMCS "Servers" entry under "Assigned IP Addresses" in the following format:DaemonID,IPAn example of such a list with dedicated IPs for the daemons 1 and 3 would be:
1,192.168.1.1 1,192.168.1.2 3,192.168.1.5 3,192.168.1.6
The module will first select the daemon the server is created on by taking the first daemon that has enough free memory to accommodate the requested server. Once the daemon is chosen it checks if a dedicated IP is requested, this is the case if the "Dedicated IP" setting of the product is "If available" or "Yes". It will then look up the available dedicated IPs and set the server up with one if found.
The dedicated IP is removed from the "Assigned IP Addresses" when it is assigned to a server and it will be written back when the server is terminated through WHMCS.
The provisioning process will fail if "Dedicated IP" is set to "Yes" and there is no dedicated IP available. It will continue normally if the setting is set to "If available".
Setup on Specific Daemons
You can restrict the daemon a product will be provisioned on by specifying a list of allowed daemon IDs in "Allowed Daemons" under the products "Module Settings".If this contains daemon IDs, the module will only consider daemons that match this list. If the list is empty, all daemons will be considered for the new server.
An example value for "Try Daemons" is:
1,3,5This will cause the new server to be set up on one of the daemons 1, 3 or 5.
Server Location Selection
This feature builds on the daemon list mentioned above (setting "Allowed Daemons" under "Module Settings"). Instead of only listing daemon IDs you can also list different lists for different locations:1,California:2,3,Florida:4,5Now you have the daemons 2 and 3 assigned to the location "California", daemons 4 and 5 assigned to location Florida and any other location will use daemon 1.
To tell the module which location to use, you can add either a "Configurable Option" or a "Custom Field" for your product that contains the string "location" in its name. E.g.:

Another usage scenario would be to chose the disk type if you have different severs with different quality/service:
Premium:1,2,Regular:3,4,5
To use more descriptive names or use commas in the displayed location name you can use the "Friendly Display Names" format of WHMCS as described here:
Addons and Configurable Options - Friendly Display Names
Welcome Mail
The following variables are relevant to communicate required information to the customer:- {$service_server_hostname} - The control panel URL
- {$service_dedicated_ip} - The IP:port of the created Minecraft server
- {$service_domain} - The ID of the created Minecraft server, useful for building links directly to the server view
- {$service_username} - The Multicraft login username
- {$service_password} - The Multicraft login password
Troubleshooting
The module will send out log mails according to the setting "Enable Log Mails" in the products "Module Settings". If the provisioning doesn't work or if you want to see what exactly the module is doing you should enable the log mails and set "Log Mail Recipient" to the email address you wish to receive the log mails on (also in the products "Module Settings").Error: "Invalid API key" or wrong server selected during setup
This can happen because WHMCS assigns the wrong server entry to the product. Make sure you have selected the correct server group in your products under "Module Settings" and check the API key in the Servers entry.If this is the case and you're still seeing the same issue also make sure that the "Fill Type" of your server group(s) is set to "Add to the least full server".
Client Profile
In the client profile service view you can see data for this particular server and control it using the "Module Commands". Special fields used by Multicraft:- Domain
This is used to store the server ID so the module knows which server this service is connected to when running terminate and other module commands - Dedicated IP
This is the IP address and port of the Minecraft server. It's not necessarily a dedicated IP - Username
The Multicraft login username - Password
The generated Multicraft login password. Note that if the user changes this in the panel it won't be updated here. This is only the initial password
