How to manage Spigot Minecraft server

• IP Address: 128.195.133.148

• User accounts: local user “mcuser” (ask sscs@uci.edu if you do not know the password). Specific SS2K domain accounts can also be setup to login.

• Local group: the group “mc-research” is setup with write access to the necessary directories for rebuilding spigot and managing minecraft server instances. The mcuser and certain domain accounts are setup as members of this group.

All scripts can be run with the “--help” option to get more detailed usage information. For more details about how to use the scripts, see the sections below.

• spigot-build.sh [version] - rebuild the spigot.jar, optionally to a specified version number
• start-mc.sh [port] - start a new minecraft server instance on a random port, or the optionally specified port

When the start-mc.sh script starts a minecraft instance, it runs it in a screen so you can connect to the server console later to check it or to give it the “stop” command

Send server to background without shutting down the server

• Simply exiting the terminal window or putty session
• Ctrl+a then d (Press ctrl+a, let go, then press d)

screen names will be of the format “mc-<port>”

• screen -list - list the currently running screens
• screen -r mc-<port> - reconnect to the screen named mc-<port> which corresponds to the minecraft instance listening on that port number
• screen -dr mc-<port> - forcibly disconnect existing connections to the screen, and reconnect, essentially taking over all other connections

The directory /usr/local/mc-research/template is the template directory that will get used to create new instances of minecraft when you run the script start-mc.sh. You should customize this template as needed.

• Edit the file /usr/local/mc-research/template/server.properties to meet your needs (change settings like gamemode, difficulty, allow-flight, etc)
• Upload the world directory (in the current template, the “test” directory is the saved world), and make sure the setting “level-name” in server.properties is set to the name of your world directory.
• Make sure there is a eula.txt file in the template directory, with the setting eula=TRUE (this should already be there, unless you replace the entire template directory).
• ensure there is a spigot.jar file or valid symlink

Spigot is a community built minecraft server which is supposed to be high performance and make it easier to work with server plugins. The researchers need this instead of the vanilla minecraft-server.jar because they use specific plugins that work with the spigot.jar server.

You need to re-build spigot.jar each time there is a minecraft client update. As of this writing, minecraft is on version 1.13.2, but version 1.14 is in pre-release and my Java Edition client updated to 1.14. You will need to make sure that the correct version of the spigot.jar file is in your minecraft server directory.

You can build spigot using a simple script on the server:

spigot-build.sh [version]

This means you can just type “spigot-build.sh” and hit enter to build the “latest” official release (not pre-release). If you want to build a pre-release or older release, you need to type the exact version number you want, like this “spigot-build.sh 1.14”

You can run “spigot-build.sh --help” to get a brief description of the script and usage information.

The result of this script is a file called spigot-<version>.jar where <version> is the actual version number. If the script is able to, it will try to copy this file into the TEMPLATE directory used by the start-mc.sh script (see below), and setup a symlink to it called just “spigot.jar”.

• NOTE: the spigot-build.sh script will NOT automatically update the spigot-<version>.jar file in any existing minecraft instances. You will have to manually stop any running instances and update the spigot.jar symlink (see below)

Old versions of the file spigot-<version>.jar are saved in an “old” directory under /usr/local/spigot. If needed, you can look there for a specific version number rather than rebuilding it. You would have to copy the desired version into the specific minecraft instance location, or to the template if you want to update the template, and then create a spigot.jar symlink pointing to it.

The minecraft template directory and each specific instance under the named <port> directories must have a spigot.jar symlink (a symbolic link) that points to the desired version of the file.

For example, you might have a spigot-1.13.2.jar file and a spigot-1.14.jar file, but whichever one spigot.jar points to is the one that will be loaded:

# change directory to the template directory (where you want to copy the new spigot-version.jar file to)
cd /usr/local/mc-research/template
# copy the desired version of the file into the template directory
cp /usr/local/spigot/old/spigot-1.13.2.jar ./
# remove an existing spigot.jar symlink, if there is one
rm spigot.jar
# create a new symlink (format is "ln -s <linktarget> <linkfilename>")
ln -s spigot-1.13.2.jar spigot.jar

This script is used to start new minecraft spigot server instances on either a random port or a specific port specified as a command-line argument. When complete, it sets up a screen with the minecraft server console running. The screen is named like “mc-<portnumber>” (i.e. mc-25570), and you can reconnect to this screen to manage or interact with the minecraft instance.

The port range 25570 to 25599 is hard coded into the script as the valid port range to use for running minecraft spigot servers. These ports are opened in the system firewall to allow incoming connections. If a different port range is required, then the script must be updated and the system firewall must be updated to match.

The script start-mc.sh should be used to start a new instance from the template on a new port. The script should not be used to re-start or manage existing instances. For a desired port <portnumber>, if the directory /usr/local/mc-research/<portnumber> already exists, you should see below for how to manage your minecraft instance instead of running this script.

Simply run this command to start a new minecraft instance on a random port within the valid port range. It will print details about which port is used and how to connect to the minecraft server console.

start-mc.sh

If you know which port you want to use, you can specify it on the command line. Keep in mind, it must be a valid port in the range defined above. For example, if I want to start a new instance on port 25570, I would use this command:

start-mc.sh 25570

To see which instances are currently running, use screen:

screen -list

To see which instances exist, even if they are not running, check the contents of the directory /usr/local/mc-research/:

ls /usr/local/mc-research/

If a minecraft instance is already running as shown by screen -list, then you can reconnect to it to stop it or otherwise interact with it. For example, if screen -list shows the screen name “mc-25570” is running, then I use this command to connect to it:

screen -dr mc-25570

You can safely close your PuTTY or Terminal session, and minecraft will continue to run. Or you can disconnect from the screen and return to your command prompt using Ctrl + a, d (hold the Ctrl key and press a, release both keys, then press d).

You will need to stop the minecraft instance when you are done using it. First connect to the screen session screen -dr mc-25570 and then send the stop command. The minecraft instance will save the world and then shutdown, and the screen will close as well.

screen -dr mc-25570
stop

If you have stopped a minecraft instance but would like to re-start it, you can do so by running the “./start.sh” command inside the specific instance directory. For example, if I previously had an instance running on 25570, but I stopped it (screen -list does not show it running), then I can re-start it like this:

cd /usr/local/mc-research/25570
./start.sh

This will re-create the screen named “mc-25570” with the minecraft server console inside.

You can see all the existing worlds in the directory /usr/local/mc-research/. Before you move or copy these files, make sure the corresponding minecraft instance is stopped!

You will need to clean up the world directories when you are done with them. This will involve stopping the minecraft instance and them moving the corresponding world directory to some other location. As long as the world directory exists in /usr/local/mc-research/, that port will be reserved and not available for future use.

I recommend archiving the world directory somewhere for your future use. The home directory of the user “mcuser” has an “archive” directory you can use to temporarily store these world archives, but it may be prudent to copy these using SFTP to your own computer or a network shared location.

I also recommend renaming the world directory when you archive it, so that you can more easily identify it later.

For example, if I am archiving the world 25570:

mv /usr/local/mc-research/25570 ~/archive/20190506-jnilsson-exp1

Screen will tell you at the bottom of the terminal: [Press Space or Return to end.]

Do so, and when the terminal clears, type exit