Minecraft module for Puppet

puppet-minecraft installs and configures your Minecraft or CraftBukkit server with Puppet!

This is a derivative work of Branan Purvine-Riley's Minecraft module, with improvements including: version selection, CraftBukkit support, a plugin resource, and settings managed via templates. It is released under the original Apache License, Version 2.0.

This module has been tested on Ubuntu Server 12.04.4 with Puppet 3.8.7.

Usage

The simplest possible usage is:

include minecraft

This entire class is parameterized (see the minecraft class for details), and can be configured through hiera.

Parameters are available which control how the Minecraft installation behaves:

• user: The user account for the Minecraft service
• group: The user group for the Minecraft service
• install_dir: The directory in which Minecraft stores its data
• source: Minecraft (semvar) or CraftBukkit ('recommended', 'beta', or 'dev'), or direct source (URL for wget)
• autostart: Start the service at boot
• manage_java: Manage the JRE package
• heap_size: The maximum Java heap size for the Minecraft service in megabytes
• heap_start: The initial Java heap size for the Minecraft service in megabytes

Minecraft Versions / CraftBukkit Builds

A particular version of Minecraft server can be downloaded by specifying the source parameter. This parameter accepts a semantic version (representing a vanilla Minecraft server), a snapshot version, or for a CraftBukkit installation, one of 'recommended', 'beta', or 'dev'. Latest vanilla version as of this writing is 1.7.5.

Please note that once a JAR file (the server) has been downloaded to install_dir, if you want to switch, you will need to manually remove it so that the wget::fetch resource can update; this is a good thing as it means the tags (e.g. "recommended") will not auto-update your server. This is good because you must beware incompatibilities among Minecraft and CraftBukkit versions with world files, settings, etc, so backup and test thoroughly before you update. (At least rolling back to an old version is easy.)

Speaking of old versions, prior to the release of Minecraft 1.6, the downloads were hosted at a different location, but since these are quite old, this module does not currently support it. Submit a Pull Request if you add support, or make an issue if you want me to do so.

Server configuration

Full configuration of the Minecraft server is supported. Simply specify the parameter with the server setting when declaring the class:

class { 'minecraft':
  source     => 'dev',
  heap_size  => 2048,
  difficulty => 2,
  motd       => 'Managed by Puppet!',
  ops        => [ 'op1', 'op2' ]
}

Hiera configuration can also be done. In YAML:

minecraft::source: 'dev'
minecraft::heap_size: 2048
minecraft::difficulty: 2
minecraft::motd: 'Managed by Puppet, with Hiera!'
minecraft::ops:
  - 'op1'
  - 'op2'

Note that the server property name will use an underscore instead of a dash, and may not exactly match the server.properties name. Also, refrain from using 'undef' for the server properties, as Puppet will place 'undef' as a string in the template; instead, use the emptry string: ''. (It's either this or add a bunch of template logic to check for an undef value first, for every parameter, do it and Pull Request if you'd like.)

Managing players

This module manages the Minecraft player settings through templates. To add players to a particular list, declare an array of them:

class { 'minecraft':
  ops                => 'me',
  banned_players     => [ 'griefer', 'badboy' ],
  banned_ips         => '127.0.0.1',         # Don't actually do this
  white_list_players => [ 'my_best_friend' ] # Minecraft auto-includes ops
}

Note that when any of these parameters is set to undef, Puppet will not manage the corresponding file, allowing you to manage it via commands in Minecraft. However, if specified, Puppet will manage the file, and overwrite any manual changes on the next application of Puppet. (There is also the "replace" attribute on the Puppet file resource, but this is not what we want because, if the file is being managed, we want changes in the manifest to be updated in the files.)

To enable the whitelist, you must both set it to true in the class, and add players to the whitelist here, as they affect separate templates. Additionally, blacklists (banned IPs/players) is pointless if the whitelist is enabled, and is only shown here concurrently for demonstration purposes.

Java

If manage_java is true, this module will use Puppetlabs' Java module to install the necessary Java Runtime Environment.

Adding CraftBukkit Plugins

CraftBukkit plugins can be installed by using the defined resource minecraft::plugin. You must specify the plugin name (lacking the '.jar' file extension) and the complete URL for the download source.

Dynmap Example

The Dynmap plugin can be configured like this:

minecraft::plugin { 'dynmap':
  source => 'http://dev.bukkit.org/media/files/757/982/dynmap-1.9.1.jar'
}

Or using Hiera like this:

minecraft::plugins:
  dynmap:
    source: http://dev.bukkit.org/media/files/757/982/dynmap-1.9.1.jar

Once enabled, a web-based map of the server will be available at localhost:8123. James Fryman's nginx module could then be used to proxy the server through map.domain.tld like thus:

nginx::resource::vhost { 'map.domain.tld':
  proxy            => 'http://localhost:8123',
  proxy_set_header => [ 'Host $host' ],
}

Or again in Hiera,

nginx::nginx_vhosts:
  map.domain.tld:
    proxy: http://localhost:8123
    proxy_set_header:
      - Host $host

Note that Nginx setup is not within the scope of this module, and is simply provided as a tip.

Rcon Example

rcon can be enabled to subsequently access the server's console.

class{'minecraft':
  enable_rcon   => true,
  rcon_port     => 1234,
  rcon_password => 'foo',
}

A rcon client e.g mcrcon can be used to connect.

# ./mcrcon  -c -H 127.0.0.1 -P 25575 -p 1234 -t
Logged in. Type "Q" to quit!

Caveats

This package uses Puppetlabs' stdlib module for the ensure_resource function, which it uses on the screen package (utilized for running the Minecraft server as a background service). This is currently the safest way to declare a possibly-conflicting dependency.

Testing

Testing of this package occurs on an Ubuntu 12.04.4 LTS machine, using Puppet 3.4.3. This is made easy using vagrant, and my own box.

Copyright

My contributions as indicated by the git repository's history are Copyright 2014 Andrew Schwartzmeyer, and as stated above, are released under the included license.

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v5.0.0 (2020-11-08)

Full Changelog

Breaking changes:

• modulesync 2.7.0 and drop puppet 4 #65 (bastelfreak)

Merged pull requests:

• modulesync 3.0.0 & puppet-lint updates #72 (bastelfreak)
• Remove duplicate CONTRIBUTING.md file #68 (dhoppe)
• Allow puppetlabs/stdlib 6.x, puppetlabs/java 4.x and puppet/archive 4.x. #66 (alexjfisher)

v4.1.1 (2018-10-17)

Full Changelog

Merged pull requests:

• modulesync 2.2.0 and allow puppet 6.x #61 (bastelfreak)
• allow puppetlabs/stdlib 5.x #59 (bastelfreak)

v4.1.0 (2018-08-15)

Full Changelog

Implemented enhancements:

• Fix namespacing #6
• Use defined types to allow for multiple servers/worlds per node #4
• Clean up using default resource attributes #1

Fixed bugs:

• Find some way to not restart every provision #2

Merged pull requests:

• allow puppetlabs/java 3.x & puppet/archive 3.x #57 (bastelfreak)
• Remove docker nodesets #53 (bastelfreak)
• drop EOL OSs; fix puppet version range #52 (bastelfreak)

v4.0.0 (2017-11-17)

Full Changelog

Implemented enhancements:

• let rcon.port and rcon.password be set #41 (traylenator)
• system accounts for user and groups #40 (traylenator)

Merged pull requests:

• bump puppet version dependency to >= 4.7.1 \< 6.0.0 #48 (bastelfreak)

v3.1.0 (2017-02-11)

This is the last release with Puppet3 support!

• Modulesync

2016-12-25 Release 3.0.2

• Modulesync with latest Vox Pupuli defaults
• Fix broken init at Ubuntu
• Fix broken dependencies in metadata.json

2016-08-18 Release 3.0.1

• First release in the Vox Pupuli namespace
• modulesync with latest Vox Pupuli defaults
• Drop of Ruby1.8.7 support
• Split server_setting defined type to separate file

* This Changelog was automatically generated by github_changelog_generator