A Minecraft Server wrapper for OSX and Linux (and any othe POSIX-compatible OS).
mcwrapper enables a Minecraft server admin to easily start and stop their server, send
commands, and also do safe, automatic world data backups.
I'm MC Wrapper and I'm here to say that I wanna wrap up minecraft so everything'll be okay.
mcwrapper has been designed for ease of use and simplicity, but also kept developers in mind.
It provides facilities for reading configuration options from Minecraft Server and
itself and also has a robust collection of status codes that it returns when it's run.
mcwrapper can now be installed via RubyGems.org. To install, simply run the following command:
gem install mcwrapper
This will install a new executable in your RubyGems installation's
bin folder. To verify
that it installed properly, you can run:
This should show your currently installed version.
If you don't have
minecraft_server.jar installed on your machine:
mkdir minecraft_server cd minecraft_server mcwrapper install
Follow the instructions (press enter when prompted). This will download the current version
minecraft_server.jar from Mojang and place it in the correct location.
To start Minecraft Server,
cd into the directory with
minecraft_server.jar and execute:
The above will start up a Minecraft server instance using default settings. All support files
related to mcwrapper will be stored in the
Basic usage is:
mcwrapper <action> [ <action_params> ]
Use the help action to see a full breakdown of usage:
See the Configuration section below for instructions on modifying the default configuration and
See the wiki page for actions for detailed information:
mcwrapper is configured using environment variables, but you can also specify these settings
mcwrapper searches for this file, in the following order, in
the following places:
All parameters that can be set in this file can also be set in your shell's environment either
export directly or by putting in your
mcwrapper.conf file and other configuration is not required as it has sensible defaults
and will try to find the location of
minecraft_server.jar on its own (starting with the
current directory). An example
mcwrapper.conf-example file is located in the distribution which
contains documentation and examples of all configuration options.
See the Configuration wiki page for detailed information:
mcwrapper uses 2 files:
mcwrapper.pid-- the pid of the currently running process. This is used by
mcwrapperfor sanity checks but can also be used by 3rd party scripts to see if
command_input-- the FIFO used for communicating with the server.
The names and locations of the above files are both configurable in
You can run arbitrary commands either through the mcwrapper script as seen in the Quickstart
or you can output commands directly to the
command_input FIFO. This is handy if you write
re-usable Minecraft scripts.
Examples of working directly with the FIFO:
echo "tell spizzike you are awesome" > command_input
If you have a file called
gimmie_diamond.mcs containing the following text:
give spizzike 264 give spizzike 264 give spizzike 264 give spizzike 264 give spizzike 264 give spizzike 264
You can run that all through the Minecraft server with the following command:
command_input < gimmie_diamond.mcs
Backing Up Minecraft Data
Since it's not safe to back up the world data while the server is running, you need to force a save, then disable writing world data to disk during a backup.
mcwrapper contains a backup action for just this purpose. To back up your current world data
directory, run the following command:
mcwrapper will read your
server.properties file to learn the location of your world data
and, after flushing anything in memory, creates a timestamped directory in the minecraft server
directory and creates a symlink to the latest backup called
By default, the backup action will simply copy your world data and server configuration (white
lists, server.properties, ban lists, etc) into the backups directory, but it can be configured
to zip or tgz the backup data. See
mcwrapper.conf-example for information on this.
mcwrapper lives in
backup will do the
/usr/local/minecraft/backups/YYYYMMDDHHMMSSwhere YYYYMMDDHHMMSS is the current timestamp
/usr/local/minecraft/worldand any other configuration data in
/usr/local/minecraftinto the above directory
- create a symlink to the latest backup at
- delete old backups. Defaults to keeping the latest 5.
The name of the
latest backup can be configured by editing that setting in
can also configure how many previous backups are kept. Again, see
information on doing this.
For an example of doing automated backups via
cron see the wiki:
Restoring from a Minecraft backup
If you ever find a need to restore from a previous world data backup,
mcwrapper now using the
restore action and passing a path (full or relative) to the backup you wish to restore:
mcwrapper restore backups/20111118123456
The above example will perform the following actions:
- gracefully stop the Minecraft server if it's running.
- do a non-clobbering backup of the current world data. This means that regardless of what your backup retention settings are, it will not delete any while creating a backup of the current world data.
- copy the specified backup directory into the servers's world directory.
- start Minecraft server up if it was previously running.
In addition to the above, a file is also created inside the world directory called
RESTORED_FROM which contains the argument specified to the
The Future (Todo List)
In the future I aim to create sysV init scripts for Linux (Ubuntu flavoured) and OSX launchd configs. I also plan on including Minecraft backup support to SnapBackup, my backup script (http://github.com/spikegrobstein/snapbackup).