How-To's


Content

Users and Players

Multicraft makes a difference between users and players. Users are registered users that log in to the control panel and can use various functions depending on their access rights for a specific server. Players are created as soon as they are seen by a minecraft server. Each server has a separate list of players.
Players can be assigned to users. By doing so the player inherits the role of the user. The players role can also be adjusted without linking it to a user so it is optional for players to register.


Private Servers

To make a server private just set its "Default Role" to "No Access". The default role is the role assigned to all users/players that don't have any other role assigned to them.
To allow access for a player to a private server you can either create the player and assign him a role greater than "No Access" or edit the player if he already exists.


Commands

You can define new chat commands or change the role required to run built-in commands.
The "Prerequisite" field in the command create/edit form refers to another command that has to be run before this one. Commands fail silently if the user doesn't have the required role.

To run a command the player needs to have a role greater than or equal to the one defined in the command settings and say the string defined in the "chat" setting of the command in-game:
asay Hello everyone!

When creating a new custom command you can define what is run on the Minecraft server by changing the "Run" field. If the command is preceded by "multicraft:" the command that will be run is the Multicraft command that has the "Chat" field matching the specified string, see the MOTD example below. The following special sequences can be used in a command:
%n The players name
%1, %2, etc. Every %X gets replaced by the X-th argument the player supplied (arguments are space separated)
%s The whole argument string supplied. If %s is used multiple times the argument string is split by spaces as many times as there are %s arguments
%l The players access level
%o Empty string (can be used to separate %1, %2, etc. from a number)

Multiple commands can be separated using a semicolon ";". To escape the semicolon use a backslash "\;". Take care not to insert a space before a command (i.e. after the semicolon) as Minecraft won't interpret that.


Built-in Commands
Built-in commands can be called - just like Minecraft console commands - by using them in the "Run" field.
You can also provide parameters in the "Run" field already, for example a command with "builtin:tell_level admin" in "Run" will cause a message to be sent to every player who is an admin. The player doesn't have to specify the level himself because it's already provided.

Command Parameters
builtin:asay message Prints "message" as the server
builtin:backup Creates a new backup zip file
builtin:date Prints the current date
builtin:give id [amount] Gives the player the item with id "id". If amount is not specified 64 blocks are given.
builtin:kick target Kicks "target" from the server
builtin:list Tells the list of players on the server to the player
builtin:restart Restarts the server
builtin:restart_empty Restarts the server only if no players are online
builtin:save Saves the world
builtin:saylist Prints the list of players on the server to everyone
builtin:script name Runs the script "name". The script has to be defined in the scripts.conf file
builtin:start Starts the server
builtin:stop Shuts down the server
builtin:stop_empty Shuts down the server if no players are online
builtin:summon target Teleports "target" to the player
builtin:tell_level level message Tells "message" to all players with their level greater than or equal to "level". "level" can be numeric or one of: user, mod, admin, owner
builtin:time Prints the current time
builtin:tp target Teleports the player to "target"
builtin:tp_other player1 player2 Teleports "player1" to "player2"


Running Scripts
The built-in command "builtin:script" enables the users to run scripts you have defined for them in a special config file. By default this config file is called "scripts.conf" and expected to be in the Multicraft base directory (where the multicraft.log lies). You can change the path/name of this file in your multicraft.conf.
The format of the file is:
[cmd1]
servers=all
command={BASE_DIR}/script1.sh

[cmd2]
servers=2,3,7
command={BASE_DIR}/script2.sh

[dangerous]
servers=1
command={SERVER_DIR}/userscript.sh
The value in the [] brackets is what the user puts after "builtin:script". "servers" lists the server IDs of all servers that can run this command ("all" for all servers). "command" is the path to the script to run. The last command is called "dangerous" because it runs a script that lies in the server directory which means that the user can modify this script.

The following placeholders can be used in "command":
Placeholder Example
{BASE_DIR} /home/minecraft/multicraft The base Multicraft installation directory
{DAEMON_DIR} /home/minecraft/multicraft/bin The path to the Multicraft daemon executable
{DATA_DIR} /home/minecraft/multicraft/data The path to the daemon database (if using SQLite)
{JAR_DIR} /home/minecraft/multicraft/jar The path to the JAR directory
{SERVERS_DIR} /home/minecraft/multicraft/servers The directory that contains all the server base directories
{SERVER_ID} 6 The server ID of the server running the command
{SERVER_DIR} /home/minecraft/multicraft/servers/server6 The base directory of the server running the command
{WORLD} world The name of the current world
{JAVA} java The default Java executable
{START_MEMORY} 1024 The amount of memory allocated on server startup
{MAX_MEMORY} 1024 The memory limit for this server
{JAR_FILE} minecraft_server.jar The JAR file used by this server
{JAR} /home/minecraft/multicraft/jar/minecraft_server.jar The full path of the JAR in use
{IP} 192.168.1.24 The IP of the server
{PORT} 25565 The port of the server
{MAX_PLAYERS} 16 The number of player slots for this server
{DAEMON_ID} 1 The ID of the daemon controlling this server
{PID} 2589 The process ID of the running server process
{PID_FILE} /home/minecraft/multicraft/servers/6.pid The file containing the servers process ID

In the script itself you'll have access to the same values listed above through environment variables. The base directory, for example, can be output using
echo Base directory: $BASE_DIR


Examples
  • Verbose kick
    Chat kickmsg
    Run say %n: Kicking %1 (%2);kick %1
    "Admin" says:
    kickmsg Duke "Foul language"
    
    Result: The player "Duke" gets kicked and everyone sees the message "Admin: Kicking Duke (Foul language)".

  • Give multiple items
    Chat armor
    Run give %n 310;give %n 311;give %n 312;give %n 313
    "Admin" says:
    armor
    
    Result: The player "Admin" receives a full diamond armor set.

  • List online players in MOTD (message of the day)
    MOTD functionality available as of b1.0.9, running other Multicraft commands from a custom command available since b1.0.10
    Chat motd
    Run multicraft:list
  • Running an PHP script on an external server regularly
    First you need to define a section in your "scripts.conf":
    [extphp]
    servers=all
    command={BASE_DIR}/extphp.sh
    

    Then you need to create the script you reference in the config file:
    #!/bin/sh
    /usr/bin/wget -qO- "http://www.example.com/myscript.php?server_id=$SERVER_ID"
    
    This script needs to be executable by the Multicraft user.

    Next, define the command:
    Chat (empty because you don't want to run this by chat)
    Run builtin:script extphp
    Then create a new scheduled task and select the newly created command.


Custom JAR Files

We do not take any responsibility for any of the links used in this and the following sections regarding custom JARs. These links are provided by the JAR authors themselves and they are not checked by us

All that is required to use a different server JAR is to place the file in the "jar" directory of your Multicraft installation and then setting the "JAR File" field in your server settings to the name of the new file.
This will work fine for a vanilla Minecraft JAR, however, Craftbukkit JARs and other mods require different settings as their console output differs from the one of vanilla Minecraft. Also, just placing the JAR file in there will not make it appear in the JAR selection in your server settings so users can't select it.

This is where the ".jar.conf" files come in to play. These files are used to determine the JAR file selection in the server settings and they are also capable of completely reconfiguring the output that Multicraft expects from the server. They are flexible enough to even run different Games with the correct settings, see our Facebook post on using Multicraft for Terraria servers.

For most users the supplied .jar.conf files will be enough. If you put a new Craftbukkit JAR in place you can just copy the existing "craftbukkit.jar.conf" to a new name, e.g. "craftbukkit_dev.jar.conf" and then edit the ".jar.conf" file to match the new JAR settings. Of primary importance is the "name" setting so it can be distinguished from the other JARs in the selection. The "source" and "configSource" settings should also be edited to make sure it's not overwritten with the files listed in the old ".jar.conf". The "source" setting defines where the JAR is downloaded when the update function in the panel is used, the "configSource" setting defines where the current ".jar.conf" will be downloaded (if you don't change that your ".jar.conf" will be overwritten with whatever is found under "configSource").

The sections "[commands]" and "[parse]" are for advanced users only. They allow remapping server commands and changing the regular expressions used for interpreting console output. If you have further questions about those sections you can contact us.

CanaryMod

You can simply download the canarymod.jar.conf file and place it in the "jar" directory of your daemon to be able to use CanaryMod like Craftbukkit or vanilla Minecraft.

Alternatively you can directly add CanaryMod in your panel using the following values under Settings->Update Minecraft->Add or Remove Files:

The "File URL" is:
http://dl.canarymod.net/latest.php?type=2
The "Conf URL" is:
http://www.multicraft.org/download/conf/?file=canarymod.jar.conf

Tekkit/FTB

Tekkit and FTB can be run using the craftbukkit.jar.conf but please note they are both not officially supported at the moment. According to user feedback, the following instructions can be used to set up a Tekkit/FTB server:
  • Make sure your .conf files for Craftbukkit are up to date under Settings->Update Minecraft
  • Copy the craftbukkit.jar.conf to Tekkit.jar.conf or ftbserver.jar.conf (case sensitive!)
  • Edit the new .jar.conf and change the setting "name" to how you want it to appear in the JAR dropdown
  • Set the "config" and "configSource" settings to empty as there are no official download locations for the JAR or the .conf
  • Download the Tekkit/FTB package
  • Put the Tekkit.jar or ftbserver.jar from the Tekkit package into the daemon "jar" directory, next to the .jar.conf you just created
  • Extract the Tekkit archive into the server directory where you intend to use Tekkit
  • Make sure the files you have just extracted have the correct owner, it needs to be mcX:mcX, where X is the server ID
  • Select the Tekkit/FTB JAR in the drop down for the server you have extracted the files to and start the server

StarMade

StarMade can be run using the StarMade.jar.conf file below but please note that StarMade is not officially supported at the moment. According to user feedback, the following instructions can be used to set up a StarMade server:
  • Download the StarMade.jar.conf and place it in the jar directory of your daemon
  • Download and update the StarMade server
  • Put the StarMade.jar from the StarMade server into the daemon "jar" directory, next to the StarMade.jar.conf you just put in place
  • Put the rest of the files from the StarMade directory of the StarMade server into the server directory where you intend to use StarMade
  • Make sure the files you have just extracted have the correct owner, it needs to be mcX:mcX, where X is the server ID
  • Download starmade.sh and place it in the scripts directory of your daemon
  • Chmod the starmade.sh to 755
  • Select the StarMade JAR in the drop down for the server you have extracted the files to, save and restart

PocketMine-MP [Experimental]

PocketMine-MP can be run using the pocketmine.jar.conf file below but please note that PocketMine-MP is not officially supported at the moment. The following instructions can be used to start a PocketMine-MP server:
  • Download the pocketmine.jar.conf and place it in the jar directory of your daemon
  • Download and install PocketMine into the directory "jar/pocketmine" of your daemon
  • If you have not compiled PHP you can change the path to PHP in the pocketmine.jar.conf to the PHP binary you want to use (first argument in the "command" setting)
  • Select the PocketMine JAR in the drop down for your server, save and restart

Spigot and BungeeCord

You can simply download the spigot.jar.conf or bungeecord.jar.conf file and place it in the "jar" directory of your daemon to be able to use Spigot/BungeeCord like Craftbukkit or vanilla Minecraft.

Alternatively you can directly add Spigot/BungeeCord in your panel using the following values under Settings->Update Minecraft->Add or Remove Files:

In the first field enter either "spigot.jar" or "bungeecord.jar". Leave the "File URL" empty and for the "Conf URL" enter one of the following depending on the JAR you wish to install:
http://www.multicraft.org/download/conf/?file=spigot.jar.conf
or
http://www.multicraft.org/download/conf/?file=bungeecord.jar.conf

You can then go to Settings->Update Minecraft, select the new entry and update the "JAR" file normally.

Server Settings

The "IP Auth Role" in the server create/edit form defines which role a player gets if the IP of the player ingame matches the IP of the user accessing the control panel (logged in or not). If this is set to "User" for example, the player can use the teleport and give functions in the "View Player" page. To disable this feature set the role to "No Access".

The "Default Role" setting has been described under "Private Servers"

The remaining role settings define what role a user must have at least in order to use the specific function for all players. I.e. if "Summon Role" were set to "Guest" every player could summon other players.

The "Base directory" is the directory in which all the worlds used by this server are stored. If you want to give a server owner FTP access to his server you can set up the FTP account with this directory as the root. Every time a different world is specified by the server owner a new directory with the worlds name gets created in this directory.
Where exactly this directory lies is decided by the "servers" setting in your multicraft.conf (see "Installation" for details).


Using MySQL / Controlling a remote server

The Multicraft control panel can connect to a daemon running on a remote machine. To enable this you have to use a MySQL database to which both the control panel and the daemon on the remote machine can connect.

Configuring the daemon
Edit your "multicraft.conf" and set the "database" setting to the shared MySQL database. Be sure to also fill in the "dbUser" and "dbPassword" settings.

By default the daemon listens on the IP address "127.0.0.1" which means only connections from the local machine will be allowed. The daemon will have to be connected to from an external machine so the address the daemon listens on has to be adapted. Edit your "multicraft.conf" and change the "ip" setting to either your external IP. If the daemon is running behind a router, you can set "ip" to 0.0.0.0 and "externalIp" to your external IP.

After changing the listening address the daemon can be connected to by anyone who knows the default password so to secure this setup you have to specify a daemon password. To do this edit your "multicraft.conf" and set the setting "password" to a password of your choice. Note that in the panel configuration instructions below we'll refer to this password in the last step of the installer.

Example:
database = mysql:host=192.168.1.1;dbname=multicraft_daemon
dbUser = root
dbPassword = yourpassword
password = yourdaemonpassword
ip = 192.168.1.2

Configuring the panel
If you still have the installer (install.php) in place you can re-run it and under "Daemon Database" put in the information of the shared database. If you've already deleted the installer script you can manually edit the file "protected/config/config.php" and set "daemon_db", "daemon_db_user", "daemon_db_pass" to match the information you have put in your "multicraft.conf".

If the database is not yet initialized you can use the installer (install.php) to initialize it.

The same password you have put in your multicraft.conf has to be used on the panel as well, you can either change the setting "Password for daemon connection" in the last step of the installer or you can manually edit the file "protected/config/config.php" and set "daemon_password" to your daemon password.

Example:
    'daemon_db' => 'mysql:host=192.168.1.1;dbname=multicraft_daemon',
    'daemon_db_user' => 'root',
    'daemon_db_pass' => 'yourpassword',
    'daemon_password' => 'yourdaemonpassword',


Mass deployment

With the Dynamic license one Multicraft control panel can manage multiple Minecraft instances distributed over multiple physical/virtual machines.

To use Multicraft in such a configuration:
  • Multicraft has to be configured for remote operation (see "Controlling a remote server" above) with the same database configuration for all the daemons
  • Every daemon has to have a unique ID listed in its configuration file (setting "id" in your "multicraft.conf")
Once this is done each server can dynamically be assigned to one of the running daemons. The daemons are automatically detected as soon as they are started trough an entry they create in the shared database.


Configure "Support" menu item

The "Support" menu item will only be displayed if you have a contact email defined. You can configure the address in the last step of the front end installer or by editing "protected/config/config.php" and setting "admin_email" to your email address. For example:
    'admin_email' => '[email protected]',


Adding Region Fixer support

Multicraft comes with a feature that allows you to run an older tool called Chunkster. This tool does not work with the new Minecraft world format anymore but you can use the same feature to launch the new "Region Fixer" (View on GitHub).
In order to configure Multicraft to use Region Fixer instead of Chunkster you can use the following instructions:

  • Download and extract Region Fixer to the "jar" directory of your daemon and make sure it's in a directory called "region-fixer". For example:
    cd /home/minecraft/multicraft/jar
    wget https://github.com/Fenixin/Minecraft-Region-Fixer/archive/master.zip
    unzip master.zip
    mv Minecraft-Region-Fixer-master region-fixer
  • Download the following chunkster.jar.conf and place it in the "jar" directory as well, make sure it's named "chunkster.jar.conf".
  • Optional: replace all occurrences of "Chunkster" with "Region Fixer" in "protected/views/server/view.php"
  • Enable the feature under "Settings"-"Panel Configuration": "Allow Users to run the Chunkster tool"
  • Optional: edit the chunkster.jar.conf with your own parameters


Changing the port of the standalone webserver (Windows all-in-one) / I can't access http://localhost/

You can change the port the built-in Nginx server uses:
Edit "Multicraft\nginx\conf\nginx.conf" line 16, change 80 to 8080, then run "stop.bat", then run "start.bat" then go to http://localhost:8080/


API Documentation

The API documentation can be found on a separate page: API Documentation


Accepting the Minecraft EULA

Minecraft versions after 1.7.9 require you create a file called eula.txt that contains the line "eula=true" in your server directory.

For individual servers

If you just want to accept the eula for your server it is sufficient to create this file or change the line to "eula=true" if it already exists. You can use your panel FTP file access to achieve this.


For server providers

Users can use their FTP access to edit the eula.txt file as mentioned above. If you want to facilitate accepting the EULA or even automate it there are several ways you can do that using Multicraft. Below you will find a few examples.


Example 1 - Add a config file entry
You can configure the panel to treat the new eula.txt as a server configuration file so users can change it without editing the file manually. Simply go to "Settings"->"Config File Settings" and click on "New Config File Setting". Fill in the fields like this:

NameMinecraft EULA
EnabledTrue
Fileeula.txt
Options{"eula":{"name":"Accept Minecraft EULA","select":"bool"}}
TypeProperty File

Your users can then accept the EULA by going to "Files"->"Config Files"->"Minecraft EULA".



Example 2 - Add an "Accept EULA" button to the server settings (advanced)
On your panel, add the following code to "protected/controllers/ServerController.php" after line 172:
            case 'accept_eula':
                if (Yii::app()->user->can($id, 'edit')
                    && !McBridge::get()->serverCmd($id, 'run:builtin:script accept_eula')) {
                    echo McBridge::get()->lastError();
                }
                break;
Add the following code to "protected/views/server/view.php" after line 368:
    $attribs[] = array('label'=>Yii::t('mc', 'Minecraft EULA'), 'type'=>'raw',
        'value'=>CHtml::ajaxButton(Yii::t('mc', 'Accept EULA'), '', array(
            'type'=>'POST',
            'data'=>array('ajax'=>'accept_eula', Yii::app()->request->csrfTokenName=>Yii::app()->request->csrfToken,),
            'success'=>'function(e) {if (e) alert(e);}')));

Then on the daemon, create or edit the file "scripts.conf" in your daemon directory (next to the multicraft.conf file) and add:
[accept_eula]
command={BASE_DIR}/scripts/accept_eula.sh

and create a file called "accept_eula.sh" in the "scripts" directory that contains:
#!/bin/sh
echo 'eula=true' > "$SERVER_DIR/eula.txt"
And make sure it can be executed:
# chmod 755 scripts/accept_eula.sh

Please note that the script needs to use the Unix line ending format so it's recommended to create it directly under Linux instead of creating it under Windows and uploading it.

Your users can now click this button to automatically create the eula.txt file.



Example 3 - Automatically create the file (advanced, Linux multiuser only)
This is similar to the suggestion above but the script will be run automatically every time a server starts. You need to make sure your users are informed about the EULA and this acceptance.
To enable the script, simply change the "userAgentPrepare" setting in your multicraft.conf to:
userAgentPrepare=scripts/accept_eula.sh
Make sure that there is no # in front of that line. After the change the daemon needs to be restarted for the change to take effect.

The script can be created the same way as described in the previous point:
Create a file called "accept_eula.sh" in the "scripts" directory that contains:
#!/bin/sh
echo 'eula=true' > "$SERVER_DIR/eula.txt"
And make sure it can be executed:
# chmod 755 scripts/accept_eula.sh

Please note that the script needs to use the Unix line ending format so it's recommended to create it directly under Linux instead of creating it under Windows and uploading it.

This script will now run every time a server starts.