MinecraftServerControlScript
=============================

A powerful command-line control script for Linux-powered Minecraft servers.


Installation
-----------------------------
To get your server to run the script on startup, and cleanly down the server
on shutdown, you need to copy the minecraft_server script to `/etc/init.d`,
set execute permissions on the file, and instruct the system to use the script
on startup and shutdown.

The following commands will work in Debian and Ubuntu like environments, ymmv
in others.

sudo cp minecraft_server /etc/init.d/minecraft_server
sudo chmod 755 /etc/init.d/minecraft_server
sudo update-rc.d minecraft_server defaults


For Bash programmable completion support, you need to copy the mscs_completion
script to `/etc/bash_completion.d`.

sudo cp mscs_completion /etc/bash_completion.d/mscs_completion


For security reasons, the script uses a user account named minecraft rather
than root.  As such, you need to create the user before using this script:

sudo adduser minecraft

If the Minecraft server software is not located when the server start command
is issued, the software will be downloaded to the proper location:
  /home/minecraft/minecraft_server/minecraft_server.jar


Requirements
-----------------------------
I've made an attempt to utilize only features that are normally installed in
most Linux and UNIX environments in this script, but there are a few
requirements that this script has that may not already be in place:

Java 6/7 JRE   The Minecraft server software requires this.
Perl 5         Most, if not all, Unix and Linux like systems have this
                 preinstalled.
Python         Required by the Minecraft Overviewer mapping software.
GNU Wget       Allows the script to download software updates via the
                 internet.
rdiff-backup   Allows the script to efficiently run backups.
Socat          Allows the script to communicate with the Minecraft server.
Iptables       Although not explicitly required, a good firewall should be
                 installed.

If you are running Debian or Ubuntu, you can make sure that these are
installed by running:

sudo apt-get install default-jre perl wget rdiff-backup socat iptables


Mapping Software
-----------------------------
The script now uses the Minecraft Overviewer mapping software to generate
maps of your worlds.  You can download premade binaries for supported systems
(Debian/Ubuntu, CentOS/RHEL/Fedora), or build your own binary from source if
needed.


Multiple Worlds
-----------------------------
The script can handle running multiple Minecraft world servers.  See the
description for the 'create' world option below.


Firewall / NAT
-----------------------------
If you have a firewall installed on your computer, or a router using NAT
installed in your network, you will need to route some ports to your server.
Instructions on how to accomplish this are beyond the scope of this post, but
here are some things you will need to know:
  The default port for the Minecraft server is: 25565.
  If you wish to run multiple world servers using this script, you will
    want to open a range of ports (for example 25565 - 25575).

If you are using iptables, and you should be, here is a very basic ruleset
that you can use.

*filter
:INPUT DROP [0:0]
:FORWARD DROP [0:0]
:OUTPUT DROP [0:0]

# Handle loopback addresses
-A INPUT -i lo -j ACCEPT
-A OUTPUT -o lo -j ACCEPT

# Allow outbound packets if state related, and inbound if established
-A OUTPUT -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Drop stealth scans
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags FIN,SYN,RST,PSH,ACK,URG NONE
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags SYN,FIN SYN,FIN
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags SYN,RST SYN,RST
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags FIN,RST FIN,RST
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags ACK,FIN FIN
-A INPUT -i eth0 -p tcp -m tcp --tcp-flags ACK,URG URG

# Allow ICMP pings
-A OUTPUT -p icmp -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p icmp -m state --state ESTABLISHED,RELATED -j ACCEPT

# Allow port 22 for SSH
-A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT

# Allow port 80 for HTTP
-A INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT

# Allow port 443 for HTTPS
-A INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT

# Allow ports 25565 - 25575 for Minecraft world servers
-A INPUT -m state --state NEW -m tcp -p tcp --dport 25565:25575 -j ACCEPT

COMMIT


Usage
-----------------------------
All commands below assume that you are running them as either the minecraft
user or as root (through sudo).

Note: If the script is run as the root user, all important server processes
will be started using the minecraft user for security purposes.

su minecraft
/etc/init.d/minecraft_server <option>

or

sudo /etc/init.d/minecraft_server <option>


Options
    start <world>
      Start the Minecraft world server.  Starts all world servers by default.
    stop <world>
      Stop the Minecraft world server.  Stops all world servers by default.
    force-stop <world>
      Forcibly stop the Minecraft world server.  Forcibly stops all world
      servers by default.
    restart <world>
      Restart the Minecraft world server.  Restarts all world servers by
      default.
    force-restart <world>
      Forcibly restart the Minecraft world server.  Forcibly restarts all
      world servers by default.
    create <world> <port> <ip>
      Create a Minecraft world server.  The world name and port must be
      provided, the IP address is usually blank.
    delete <world>
      Delete a Minecraft world server.
    disable <world>
      Temporarily disable a world server.
    enable <world>
      Enable a disabled world server.
    status <world>
      Display the status of the Minecraft world server.  Displays the status
      of all world servers by default.
    send <world> <command>
      Send a command to a Minecraft world server.
    logrotate <world>
      Rotate the server.log file.  Rotate the server.log file for all worlds
      by default.
    backup <world>
      Backup the Minecraft world.  Backup all worlds by default.
    watch <world>
      Watch the log file for the Minecraft world server.
    map <world>
      Run the Minecraft Overviewer mapping software on the Minecraft world.
      Maps all worlds by default.
    update
      Update the client and server software packages.


To start all of the world servers, issue the command:

/etc/init.d/minecraft_server start


To create a world named alpha, issue the command:

/etc/init.d/minecraft_server create alpha 25565


To start just the world named alpha, issue the command:

/etc/init.d/minecraft_server start alpha


To send a command to a world server, issue the command:

/etc/init.d/minecraft_server send <world> <command>

ie.
/etc/init.d/minecraft_server send alpha say Hello world!


Message of the Day (MOTD)
-----------------------------
To whisper the message of the day to users as they log into the world, add a
file called motd.txt to the /home/minecraft directory.

nano /home/minecraft/motd.txt


Colors
-----------------------------
To add colors to your Help or MOTD files, insert the following color codes
into your text:
    §0 - black
    §1 - blue
    §2 - deep green
    §3 - aqua
    §4 - deep red
    §5 - purple
    §6 - gold
    §7 - gray
    §8 - dark gray
    §9 - light blue
    §a - green
    §b - teal
    §c - red
    §d - magenta
    §e - yellow
    §f - white

Example motd.txt:

§fWelcome to Minecraft!
§fToday's theme is §4red§f.
§fLook out for those §2creepers§f!


Server Customization
-----------------------------
The server settings for each world can be customized by adding certain
key/value pairs to the world's server.properties file.

The following keys are available:
    mscs-server-version - Assign the version of the server to run.
    mscs-server-jar - Assign the .jar file for the server to run.
    mscs-server-url - Assign the download URL for the server software.
    mscs-server-args - Assign the arguments to the server.
    mscs-initial-memory - Assign the initial amount of memory for the server.
    mscs-maximum-memory - Assign the maximum amount of memory for the server.
    mscs-server-location - Assign the location of the server .jar file.
    mscs-server-command - Assign the command to run for the server.
 
The following variables may be used in some of the values of the above keys:
    $JAVA - The Java virtual machine.
    $CURRENT_VERSION - The current Mojang Minecraft release version.
    $SERVER_VERSION - The version of the server that will be run.
    $SERVER_JAR - The .jar file to run for the server.
    $SERVER_ARGS - The arguments to the server.
    $INITIAL_MEMORY - The initial amount of memory for the server.
    $MAXIMUM_MEMORY - The maximum amount of memory for the server.
    $SERVER_LOCATION - The location of the server .jar file.

The following example key/value pairs are equivalent to the default values:
    mscs-server-version=$CURRENT_VERSION
    mscs-server-jar=minecraft_server.$SERVER_VERSION.jar
    mscs-server-url=https://s3.amazonaws.com/Minecraft.Download/versions/$SERVER_VERSION/minecraft_server.$SERVER_VERSION.jar
    mscs-server-args=nogui
    mscs-initial-memory=128M
    mscs-maximum-memory=2048M
    mscs-server-location=/home/minecraft/minecraft_server
    mscs-server-command=$JAVA -Xms$INITIAL_MEMORY -Xmx$MAXIMUM_MEMORY -jar $SERVER_LOCATION/$SERVER_JAR $SERVER_ARGS

The following example key/value pairs will use the latest CraftBukkit recommended build:
    mscs-server-jar=craftbukkit.jar
    mscs-server-url=http://dl.bukkit.org/latest-rb/craftbukkit.jar
    mscs-server-args=
    mscs-initial-memory=128M
    mscs-maximum-memory=2048M


Lib Notify
-----------------------------
On systems that support lib notify, you can modify the script to print a
message on your desktop of important server events.

First, you need to know the name of the display you want to route the
messages to.  This is usually ":0.0", but it may be something different on
your system.

glxinfo | grep "name of display"


If your username is different than the user used for the Minecraft server,
replace $USER_NAME in LIBNOTIFY_USER_NAME=$USER_NAME with the correct
username.

Modify the following lines of code in the script:

# To use lib-notify to print a message on your desktop of important server
events, change the following to a 1.
USE_LIBNOTIFY=0

# The username and display that notifications will be routed to.
LIBNOTIFY_USER_NAME=$USER_NAME
LIBNOTIFY_DISPLAY=":0.0"


License
-----------------------------
See LICENSE

Issues
-----------------------------
I have only tested this code in a Debian/Ubuntu environment, but there is no
reason that it shouldn't work in any appropriately configured UNIX-like
environment, including Apple Mac OSX and the other BSD variants, with only
minor modifications.  If you experience errors running this script, please
post a copy of the error message and a note detailing the operating
environment where the error occurs to the support thread, and I'll try to
work out a solution with you.

Support thread:  http://www.minecraftforum.net/viewtopic.php?f=10&t=129833