Legacy WHMCS Module Documentation

For module version 2.0 (Nov 2011)
Outdated: Please upgrade to the latest module instead

Content

• Installation
• Create "Servers" Entry
• Create Products
  • Module Settings
  • Custom Fields
• Usage
  • Selecting the Daemon by Available Memory
  • Dedicated IPs
  • Setup on Specific Daemons
  • Server Location Selection
  • Welcome Mail
  • Troubleshooting
    • Error: "Invalid API key" or wrong server selected during setup
• Client Profile

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
• 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
• 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,IP

An 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,5

This 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,5

Now 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