Blog Archive

Wednesday, September 12, 2012

How to Run Your Own Minecraft Server

Awesome architecture by Arsian qchronod. 

Minecraft is a sandbox-type game where you gather materials and use them to create things, which is about as understated a description as "the sun is a big bright light in the sky." The poster child for indie gaming success, Minecraft began as a basement coding project by hat-wearing Swede Markus Persson in 2010; it has since become a bona fide phenomenon.
In Minecraft, you play a mute protagonist in an unending retro-blocky landscape populated by lots and lots of NPCs, with no traditional adventure game-type goal other than survival. This seems easy at first. When the game begins, you invariably find yourself on a sandy beach somewhere, and a bit of experimentation quickly yields the knowledge that you can affect your environment by punching things. You can punch trees to break them apart and collect wood, for instance, which you can use to make tools, which you can use to gather more materials, which you can use to make more things. You'll just be getting the hang of the basic mechanics when night falls—and the zombies and skeletons and spiders and creepers come out to collect your soul.
As the game grew more popular, Persson (known to fans by his in-game handle "Notch") hired staff and eventually turned over daily programming duties to other folks. These days, Notch spends his days developing other games and being interviewed by famous Internet journalists, while Minecraft thrives on multiple platforms including PC, Mac, Linux, and XBox 360.
The game has an engrossing single-player component, with a core gameplay mechanism that feels like a LEGO block set—go build stuff!—but it's much more fun to make things with your friends than to labor alone. Public Minecraft servers are widely available (here's a good list), but they have an unfortunate dark side: as with any public online game, keeping out folks bent on making mischief is ultimately impossible. If you want to play Minecraft with just your friends, the easiest way to do so is to run your own server.
Your first choice, should you go this route, is whether you want to use a managed hosting provider, use a regular non-Minecraft host, or just run the server yourself. Each option has tradeoffs. Choosing to use a fully managed Minecraft host like Servercraft or BeastNode means that you'll be up and hosting within minutes of forking over your credit card number, but you may have less control.
A non-Minecraft Web host, like a virtual private server from A Small Orange, might cost more, but it gives you additional flexibility in configuration (what if you want to add mods or tweak things later, or install additional server software?).
Finally, hosting the code yourself on a dedicated server in your closet is the most complex option, but can also be the cheapest and most flexible, assuming you have spare hardware lying around. For smaller Minecraft instances where you expect to only have a couple of players—for example, if you just want to play Minecraft with your kids—you can even run the server on your main computer without needing a separate piece of hardware.
One quick note: this guide assumes that you're interested in running a Minecraft server because you're already a Minecraft player. We're not going to spend any time explaining how to actually download and set up the Minecraft client, nor will we talk about Minecraft basics like gameplay or strategy. This guide is long enough as it is!

Arsian Cogwheel's freakishly awesome flying castle, under construction.

Quick Start

The Minecraft server binaries can be downloaded from the same page as the full game. The server package is free and available as either a Windows executable or a Java .jar file for Linux and OS X (and for Windows, too, if you don't want the executable version). Grab whichever one you need.
Windows users have it easiest: simply download the executable and run it. If you don't have a Java runtime environment installed, the executable will direct you to a download page where you can get it; once installed, re-run the Minecraft server binary. This gets you a Minecraft server up and available on TCP port 25565. Connect to it with your Minecraft client and explore your shiny new world.
To run Minecraft on OS X and Linux, you'll also need a Java runtime environment installed. For OS X, you can quickly install the latest Apple-approved version of Java by opening a Terminal window (click the Spotlight icon, type "terminal") and executing the command "java". If you don't already have Java installed, OS X will automatically grab it for you.
On a Debian-derived flavor of Linux like Ubuntu or Mint, the OpenJDK Java project is available from the default repositories and can be installed with a quick sudo aptitude install openjdk-7-jre (yes, we're using aptitude instead of apt-get, and so should you! Aptitude is available by default in Ubuntu server, but you might have to install it via apt-get for the desktop version). If you feel like you need the actual, genuine, Oracle-produced Java runtime environment instead of OpenJDK, you need to follow a few more steps.
With Java installed, you can immediately start your Minecraft server by opening a terminal window and invoking it with:

$ java -Xmx1024M -Xms1024M -jar /path/to/minecraft_server.jar nogui

That's it—just like your PC brethren, you're up and running with a Minecraft world available on port 25565.
The first time you start your Minecraft server, it checks for any existing Minecraft world and configuration files. If it doesn't find any, it creates everything it needs. In a fresh install, you'll end up with a world directory containing the newly generated Minecraft map, some configuration files, and a log file. If you plan on running Minecraft under a dedicated Minecraft user account, like on a real server, you might want to pre-create that account before firing up the server, though it's not strictly necessary to do so. (We'll cover how to move the Minecraft directory shortly.)

Now it's on to the fun stuff: tweaking your server.

Arsian FoO's jungle coaster stretching off into the hazy distance. You could be riding something like this right now if you were faster at setting up a server.

Going into Details

Your Minecraft server is now running, but we can make it work quite a bit better. What if we want to run Minecraft unattended on a headless server? What if we want to run it under a different user's context, for security? What about running it as a service, so it automatically starts and stops with your computer? How do we back it up? How can we monitor it remotely? What about altering Minecraft's RAM allocation, or changing its configuration options, or even installing mods?

RAM usage at the command line

If you just want to play with your buddies and not the whole wide Internet, it's best to enable the server whitelist setting and add your buddies' Minecraft usernames to it.
The first thing you'll likely want to tweak is the amount of RAM allocated to Minecraft. It's a memory-hungry application and will, over time, gobble up as much RAM as you can throw at it; most will be used to keep chunks of terrain cached in memory. This is extremely handy if you have a busy server with a dozen or more players online all at once, since it lowers the amount of terrain data Minecraft has to pull up from disk, but it might also be a waste of memory on a lightly populated server.
As a general rule of thumb, start with 1GB and consider allocating another half a gigabyte per regular player. If you expect to have four folks regularly playing on your server, 2-3 gigabytes should be plenty.
RAM allocation is the easiest tweak to make, as it's specified in the Java command used to launch Minecraft with the -Xms and -Xmx arguments. Xms sets the starting RAM allocation and Xmx sets the maximum RAM allocation. To launch Minecraft with 2GB of RAM, use the following command on OS X and Linux:

$ java -Xmx2048M -Xms2048M -jar /path/to/minecraft_server.jar nogui

The same can be done on Windows, too, though it must be done as above, by calling Java directly, rather than by running the Minecraft server executable:

java -Xmx2048M -Xms2048M -jar "C:\path\to\minecraft_server.exe"

Omitting the "nogui" option will start the server with a (sort of) graphical console instead of a text mode console, which can be handy for executing commands on the running Minecraft server instance.
Rather than type that string of text out every time you want to manually start your Minecraft server, it's easier to copy it into a batch file and execute that instead. Linux and OS X users can put the command into a script file and run chmod +x on the file to achieve the same effect.

Options in the file

The main Minecraft configuration file is, located in the same directory as the Minecraft server .jar or .exe. Most of the entries here can be left alone, but you might want to modify a few to taste.
level-name: The displayed name of your Minecraft map. Defaults to "world," which is uncreative and boring. You will almost certainly want to change it to something more exciting.
server-port: The TCP port on which the server listens for clients. This is the port number everyone else will have to use to connect to your server. Defaults to "25565," which you may or may not want to change.
spawn-npcs: Enables or disables non-player characters like villagers. Defaults to "true," but disabling it can help with lag and memory usage.
spawn-animals: Enables or disables animals, like sheep, pigs, and cows. Defaults to "true," but disabling it can help with lag and memory usage.
spawn-monsters: Enables or disables monsters, like skeletons and zombies. Defaults to "true," but disabling it can help with lag and memory usage; also might be worth turning off if you don't want to have to fight things.
white-list: Enables the use of a player whitelist, which allows only approved players to connect and play. Defaults to "disabled," but if you're going to run a private or semi-private server, you must set this to "enabled." The whitelist itself is stored in white-list.txt and can be directly edited or modified with an in-game console command.
pvp - Enables or disables player versus player mode. Defaults to "true." If you don't want players to be able to directly damage each other, set this to "false." Note that whether set to true or false, players can always indirectly harm each other with explosions, lava, and other environmental hazards.
gamemode: Controls whether the game is set to Survival, Creative, or Adventure. Defaults to "0," which is traditional Survival mode, where players must gather resources and build things. Also available is "1," Creative mode, where players can fly around and summon unlimited building materials and are immune to damage; and "2," Adventure mode, which is broken and doesn't really work correctly.

For a comprehensive description of all of the other options in the configuration file, check out the Minecraft wiki.

Adding a connection to a Minecraft server at, TCP port 25565.

Operators, whitelists, and bans

Four other important files live in the Minecraft server directory: ops.txt, white-list.txt (which we mentioned above), and the two ban-related files, banned-ips.txt and banned-players.txt. All four can be edited directly or modified via console commands from within Minecraft. However, before logging in to your world for the first time, you'll definitely want to add your Minecraft account name manually to the ops.txt file. This designates you as a server operator and gives you the ability to run commands on the Minecraft server while logged onto it, instead of having to use the GUI console or the command line.
Once you've added yourself as an operator and logged onto your Minecraft world, bring up the chat window (which defaults to the "T" key) and type /help for a list of commands you can issue to the server. The list will include the ban command, the kick command, the whitelist command, and several others. Commands to ban players, whitelist players, or promote players to operator will cause the related text files to be modified appropriately, so you never need to mess with editing the files directly unless that's how you prefer to roll.
I mentioned it above, but it's worth repeating: if you just want to play with your friends and not the whole wide Internet, it's best to enable the server whitelist setting and add your buddies' Minecraft usernames to it. This lets them connect but will keep out everyone not on the whitelist. Having a lively server open to the public can be fun, but anonymity tends to bring with it craziness, and a totally open and unprotected Minecraft server can quickly degenerate into chaos and griefing. It sucks to spend hours and hours creating a beautiful structure, only to log on the next day to find that most of it has been torn down and replaced with a giant flaming penis.

Yes, people will troll your map.

Sunrise over the Pyramid of Zaktar.

Running Minecraft automatically

If you're going run Minecraft on an actual server, you likely will want it to automatically start when that server boots up rather than having to execute it manually. Most servers are headless or are run without a user logged in, so having Minecraft start itself up automatically is pretty much a requirement. The Minecraft server .jar doesn't come with the ability to do this natively, but tools on each major operating system can be employed to get things started.

Running as a service on Windows

There are several options for automatically running Minecraft on Windows, most of which involve downloading a service wrapper like YAJSW and configuring that wrapper to launch Minecraft. A good tutorial on this can be found here.
A far easier way, though, is to use a tool like YAMS, or "Yet Another Minecraft Server." Rather than having to deal with configuring a wrapper, YAMS is an all-in-one Minecraft server instance which comes preconfigured as a Windows service. It can even automatically accomplish some advanced configuration tasks, like setting up port forwarding on a uPnP-compatible SOHO router. This is an excellent option for folks without a lot of Windows server administration experience, as it handles most of the complexity under the hood.

Running as a service on OS X

Automatic startup on OS X is, unfortunately, a rather complex affair. The best tutorial I've found on the topic is the one on the official Minecraft wiki, here, which describes how to create a daemon account and a launchd job for Minecraft. There's far too much information to include directly in this guide, but it should be enough to get you started if running automatically under OS X is your goal.

Running as a service on Linux

Running Minecraft automatically under a Linux server distro is a straightforward and well-documented process. Briefly, you'll need a utility named screen, a user account under which to run Minecraft, and (if you're using Ubuntu, Mint, CentOS, or any other Linux distro with startup scripts in /etc/init.d/) a startup/shutdown script.
The first thing to do is to install screen, a utility which lets you take the output of a running command and direct it to a virtual terminal. This is important because the Minecraft server process needs somewhere to send its output while running, and we'll use screen to give the process a place to display what it needs to display without actually tying up a terminal on the server. Installing the utility is extremely easy on Debian-flavored distros:

$ sudo aptitude install screen

Once done, you'll need to create an account under which to run Minecraft. You could run it as root, but that's a terrible thing to do—if there are any undiscovered security vulnerabilities in the Minecraft Java application or in the Java runtime environment itself, attackers might be able to use those vulnerabilities to execute commands on your server. If the Minecraft process is already being run with root privilege, you've done half your attacker's work for them.
To create a user, run the following command:

$ sudo useradd -c "Minecraft user" -m mcuser

This will create a user named "mcuser" and will also create a home directory for that user. It's a good idea to keep all of the Minecraft files located inside that user's home directory, too, since we'll be executing Minecraft under that user's context. If you've not already set up Minecraft, create a directory named /home/mcuser/minecraft and place the Minecraft server .jar file there; if you've already got Minecraft running, stop it by logging out and issuing the /stop command (or type stop into the console), then run the following commands to move Minecraft from wherever it currently resides into mcuser's home and to change the ownership of all the copied files and directories to mcuser:

$ sudo mkdir /home/mcuser/minecraft
$ sudo cp -R /old/minecraft/location/* /home/mcuser/minecraft/
$ sudo rm -rf /old/minecraft/location
$ sudo chown -R mcuser:mcuser /home/mcuser/minecraft

I prefer doing operations like this using a copy and delete rather than a move, in case there's a problem during the move. You can also spawn a shell as root with sudo /bin/bash, so that you don't have to keep prefacing commands with sudo, if you wish.
The last thing to do is create the init script, which will get called by the server on startup and shutdown and which can also be executed manually to safely start and stop the server. There are several examples of Minecraft init scripts available, but the one I use for my Minecraft server can be downloaded here. Save the file as minecraft with no extension and move it into your server's /etc/init.d/ directory, then open it up and change anything inside it that you need to change (if you're using a different name for your Minecraft user, or a different path for your Minecraft directory, or whatever). Once it's there, run the following command to set the script to run appropriately at startup and shutdown:

$ sudo update-rc.d minecraft defaults

Then you're all set to start the server with sudo /etc/init.d/minecraft start. If you need to stop it for any reason, run sudo /etc/init.d/minecraft stop.

Server commands and log watching

Everything that happens in your Minecraft world that generates a message that gets recorded in the server.log file, so that's the file to watch if you want to know what's going on. If you're running the Minecraft server directly, rather than automatically via script or service, then the contents of the log file are echoed directly into your terminal window (or the server GUI if you're running it without the nogui option), and any commands you type into the terminal are received by and run on the server. For example, you can broadcast a message to everyone on the server with the say command. Typing "say I AM THE ADMIN" into the console results in the following for all logged in players:

Chat text entered into the console appears to other players in letters of fiery...uh, purple.

Watching the log file is also easy if you're running Minecraft as a service. On Windows, simply open the log in a text editor and look at it. For OS X and Linux, you can use the tail utility to keep a continually updating view of the log file up in a terminal window, like this:

$ tail -f /home/mcuser/minecraft/server.log

Issuing console commands to Minecraft when running it as a service, though, is a bit trickier. I've not found a good method for OS X and Windows, since I don't regularly run Minecraft on those platforms. On Linux, when employing screen as recommended above, commands must be sent through the correct screen instance, which effectively types them directly into the Minecraft console. The syntax for doing this can be gleaned from within the Minecraft startup script, since it uses the same method to pass save and shutdown commands into the Minecraft console.
You will need to be root, and then use the su tool to execute a command as the Minecraft user, and in that command you must enter what you want to pass on to Minecraft, being careful to escape all single and double quotes inside the statement. To say "hello" to all the users on the server, for example, you would need to execute the following command while logged in as root:

# su - mcuser -c "screen -p 0 -S survival-mc -X eval 'stuff \"say Hi everybody\"\015'"

You would substitute in your Minecraft user name, and also substitute in the name of the screen instance you're using (mine, as well as the default instance in the Minecraft init script listed above, is "survival-mc"). This method is cumbersome and you're usually better off simply logging into the Minecraft server with an operator-privileged user and running commands that way, but sometimes entering commands like this is necessary.

Planar_Demon's house of lava and water is a study in contrasts

Fancy extra stuff for Linux

Having run Minecraft on Ubuntu Server for almost two years, I've collected a few additional tips and tricks to make the daily admin tasks a little easier. We're going to go over a couple of things to help you out—quick and easy backups, and fancy monitoring.

Backups with rsnapshot

Use Linux long enough and you'll come across a situation where you need to use the mythical and magical rsync utility to get some files copied from one place or another. It's a differential copy utility, with the ability to look at a source and a target and only copy things to the target which have changed or which meet certain other definable criteria, sort of like robocopy on Windows. Rsync is extremely handy, but making it work correctly can require a lot of elbow grease; using it as part of a backup solution can lead to madness (or at least a whole hell of a lot of scripting).
Enter rsnapshot, which functions as a front-end for rsync and which can be used to create a whole set of browsable Apple Time Machine-style file system snapshots. Because Minecraft stores its map data spread across many different files, rsnapshot is a great way to take incremental backups of your Minecraft world without using tremendous amounts of space. You can have your backups created either locally, to another directory on the same disk, or remotely, to an NFS mount or directly to another box running the rsync server.
If you're on Ubuntu, Mint, or another Debian-ish Linux distro, you can quickly install rsnapshot from the repositories:

$ sudo aptitude install rsnapshot

Once installed, modify the /etc/rsnapshot.conf file to specify what local folders you want to back up (which for us would be /home/mcuser/minecraft), along with where you want the backups to be stored and how many backups of each type (hourly, daily, weekly, and monthly) to keep before they are pruned. Lastly, you'll need to add some entries into the system crontab file to ensure the hourly, daily, weekly, and monthly backups are executed, since this isn't set up by default.
I won't go any deeper into how rsnapshot should be configured, as it is a well-documented utility and there are many guides available on the Internet on making it work. I use it to back up to an NFS mount off of my Synology NAS, with the "hourly" backup script running once every six hours.

Super-fancy log monitoring

You know what's awesome? A fast and easy way to remotely view log files which updates in real time. You know what else is awesome? Node.js and Socket.IO. And you know what's the most awesome of all? A fast and easy way to remotely view log files which updates itself in real time, based on Node.js and Socket.IO!
Don't worry if all this Node.js and Socket.IO talk doesn't make any sense, because it doesn't have to. Meet, an extremely slick real-time remote log viewer based on some of the trendiest Web technologies available today. If you're comfortable with the command line, it's quite easy to set up; in fact, if you're using Ubuntu 12.04 server, a five-step build recipe can get you running. You'll need to start both the harvester (which sends log data to the server) and the server on your Minecraft box; you'll also need to edit your /etc/ file and add in the path to the Minecraft log file under the log_file_paths section, so that the harvester knows to watch that file.
Once this is done, you can point your browser to http://your_minecraft_server:8998 and keep an eye on your Minecraft log files in real time: is a great way to remotely monitor lots of logs, too, so feel free to add other stuff in as well.

The mod squad

The last thing we're going to talk about is how to apply mods to Minecraft. The short answer is that you sort of can't, but the short answer is misleading. The more verbose answer is that you cannot mod Minecraft directly, at least not to any great effect, but you can install a drop-in replacement for Minecraft Server which has full support for mods. It's called CraftBukkit.
CraftBukkit is a self-contained Minecraft server replacement which is built from the Bukkit API. The Bukkit project grew out of an earlier Minecraft mod project called hmod (which is no longer online, as it has been entirely superseded by Bukkit). It's not the only way to mod Minecraft (see, for example, Tekkit, a set of modifications that turns Minecraft into something like a SCADA simulation at a mad scientist's nuclear plant), but it's by far the most popular, and the majority of Minecraft modifications are created for use with CraftBukkit. In fact, in February 2012, a number of the coders behind Bukkit officially joined Mojang, the developer of Minecraft; this partnership will lead to future releases of Minecraft directly incorporating a plugin API, which will obviate the need for Bukkit as a standalone tool. Until this happens, though, CraftBukkit remains necessary if you want to use most popular Minecraft mods.
The Bukkit developers are continually working on CraftBukkit, and new builds appear frequently. Some builds are thoroughly tested and advertised as "recommended"; unless you like living on the bleeding edge, those are the ones you should run. To get started with CraftBukkit, download the latest recommended build and copy the file to your Minecraft server directory. Stop Minecraft, rename the existing server executable or .jar file to something like minecraft_server_backup.jar, and rename the downloaded CraftBukkit jar file to minecraft_server.jar. Then start the server up using your normal method.
By itself, CraftBukkit does nothing, but now that it's installed, you can go hunting for CraftBukkit mods that tickle your fancy. Want to control who can open your chests and doors? There's a mod for that. Want to wave your mouse around and make huge changes to your world like some kind of mad god? There's a mod for that. Want to add an economy with multiple currencies and interest and taxes and a lot of other things which sound ridiculous and super-tedious but which some people apparently find super-fun? Yup, there's a mod for that, too.
Not all mods change aspects of the core gameplay—some add small bits of vital functionality, like the ability to continually record the coordinates of all logged-in players. This doesn't sound immediately useful, but what if you could take that data and match it up against a map of your Minecraft world? That would be awesome, wouldn't it?

I can see my house from here!

Turns out that yes, it is indeed awesome. Several different mapping utilities exist for Minecraft, all of which render a Web-viewable portrait of your world and display it in a Google Maps-style interface in which you can zoom around to look at things. Two of these, Minecraft Overviewer and Dynmap, come with CraftBukkit plugins and can show live (or nearly live) player positions, complete with correctly skinned icons for each player.
The process of installing Minecraft Overviewer can be a little daunting if you have to build it from source and track down its myriad dependencies, but prebuilt packages for Ubuntu ban be quickly installed with aptitude after adding the correct repository. The instruction page can get you pointed in the right direction. Once it's up, you'll need to do some configuration file work to get Overviewer pointed at your Minecraft world and rendering things. Finally, to display player positions on the Overviewer map, you'll need to install this add-on.
Dynmap is far easier—you can simply download the .jar file and copy it to your CraftBukkit plugins directory (which by default is /home/mcman/minecraft/plugins) and restart Minecraft. There are a lot of configuration options you can get into to customize how it looks and functions, but nothing else is required for basic functionality.

The view from Minecraft Overviewer—there I am!

 About the creations pictured above and other stuff

The mountain-top castle is partly a collaborative effort. Qchronod prepared a lot of the terrain and infrastructure like bridges, then invited other players to construct their own towers / buildings in the area.

Zaktar's pyramid is even more impressive from the inside. It is hollow and contains an entire forest. In the near future he wants to take advantage of the upcoming "adventure" features to make the pyramid into a combat pit.

The rollercoaster is an incredible bit of work too. You really have to take a ride to appreciate the amount of work that went into it.

Comment from FOo himself: SO MUCH DEATH :scared: I can't count how many times I died putting that thing together - I still have plans on extending it further out through the jungle as well, but had to take a sanity break/get back to school. I'm also working on a glass maze in the... hollowed out mountain next to it - me and Planar_Demon already have a few challenges setup, but the maze has yet to be completed (you may suffer some spoilers if you check it out though).

Mods: The short answer is : there is no offical way of doing it (yet).
The long answer is : there are many mods out there working in multiplayer with really deep effect on gameplay (I can mention RedPower, Buildcraft, IndustrialCraft and Smart Move among others). There are modding APIs working in multiplayer (ie: Forge). Those may take a bit of tweaking to get working but you have more choice than what has been ported to Bukkit.

No comments:

Post a Comment