WHMCS Module Documentation

For module version 2.0 (Nov 2011)

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


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").



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