SocSci Computing Services Help Pages

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

===== Important directories on the server =====

^ Directory  ^ Description  ^
| /usr/local/spigot  | this is where the spigot build happens, and where the resulting spigot-<version>.jar file is put  |
| /usr/local/spigot/old  | this is where old/existing versions of the spigot jar file are put whenever you run the spigot-build.sh script  |
| /usr/local/mc-research  | this is where the minecraft instances are kept, including the template world, and any current worlds  |
| /usr/local/mc-research/template  | this is a specially named directory (the start-mc.sh script expects this name) where the template world is saved  |
| /usr/local/mc-research/<port>  | a directory named after the port number where the minecraft instances is running  |


===== Important scripts =====

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



===== Important screen commands =====

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


===== Setup the template directory =====

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

[[https://www.spigotmc.org/|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.

=== Important info about spigot version ===
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.

=== Rebuilding spigot ===
You can build spigot using a simple script on the server:<code>
spigot-build.sh [version]
</code>

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.

=== Output: spigot-<version>.jar ===
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 spigot ==
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.

=== Update spigot.jar symlink ===

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:<code>
# 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
</code>



===== start-mc.sh script =====

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.

=== Port range ===

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.





==== How to run start-mc.sh ====
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.

=== To start on a new random port ===
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.
<code>start-mc.sh</code>

=== To start on a specific port ===
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:
<code>start-mc.sh 25570</code>





===== FAQ: How to manage minecraft instances =====

=== How to see currently running instances ===
To see which instances are currently running, use screen:<code>screen -list</code>

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

=== How to re-connect to the minecraft server ===

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:
<code>screen -dr mc-25570</code>

=== How to disconnect from minecraft server screen without stopping it ===

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

=== How to stop an instance ===

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.<code>
screen -dr mc-25570
stop
</code>

=== How to re-start an instance ===

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:<code>
cd /usr/local/mc-research/25570
./start.sh
</code>
This will re-create the screen named "mc-25570" with the minecraft server console inside.

=== Where are the world files? ===

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!

=== What to do with old world directories? ===

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:
<code>
mv /usr/local/mc-research/25570 ~/archive/20190506-jnilsson-exp1
</code>

=== If you accidentally type ''screen'' without any arguments ===
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