Minecraft Relay Server (mcrelay)

A Minecraft reverse proxy server with server address rewrite.

Supports Minecraft servers and clients with version 12w04a and later (basically means release 1.2.1 and later).

Minecraft versions before 12w04a are NOT SUPPORTED!

Features

• Support reverse proxy for Minecraft servers by server address in the handshake packet which the client sends.
• Support rewrite server address and server port to camouflage a connection which uses an official server address (e.g., pretend to be a normal connection to Hypixel, avoiding their server address check).
• Support IP forwarding using HAProxy's Proxy Protocol (but it refuses any incoming connection using this protocol).

Requirements

• Linux
• libresolv.so.2 (usually pre-installed. On debian-like systems, contained in package libc6)
• libcjson.so.1 (on Debian-like systems, contained in package libcjson1)
• libsystemd.so.0 (on Debian-like systems, contained in package libsystemd0)

Compatibility

Due to Minecraft handshake restrictions, this server supports:

• Game relay on server & client with version 12w04a and later, except version 12w17a, 13w41a and 13w41b.
• MOTD relay or MOTD status notice on server and client with version 1.6.1 and later, except version 13w41a and 13w41b.

Files

• CMakeLists.txt CMake configuration for compiling.
• doc Folder of documents.
• doc/information Informational documents.
• doc/information/loglevel.info Definitions of log levels.
• doc/information/versions.json Version manifest.
• doc/configuration Configuration examples.
• doc/configuration/logrotate Configuration used by logrotate.
• doc/configuration/mcrelay Configurations read by mcrelay itself.
• doc/configuration/systemd Configuration used by systemd, when using mcrelay as a service.
• src Folder of source codes.

See the systemd configuration notes for compatibility and synchronous reload modes.

Compile

Before compiling, you need to install the cJSON and systemd development files at first.

For example, you can install them on Debian-like systems by apt install libcjson-dev libsystemd-dev.

Then you can use CMake to compile it by cmake -B build && cmake --build build, the executable file is build/mcrelay.

Additionally, if you want cross-compiling, the following CMake properties will be helpful:

• -DCMAKE_C_COMPILER: Specify an alternative compiler, CMake uses cc by default.
• -DEXEC_SUFFIX: Add a suffix to the final binary file, the file will be generated called mcrelay.

Resolver helper capacity

By default, mcrelay starts two resolver helper processes, and each helper performs at most one blocking DNS lookup at a time. Configured destinations are normally prewarmed before mcrelay reports readiness, but a large startup or reload configuration, or a burst of distinct uncached names, can contend for the two helpers and each connection's independent default 10-second route-wait deadline.

The helper count is a compile-time limit rather than a runtime configuration option. Deployments that need more parallel DNS lookups must rebuild with a larger RESOLVER_SUPERVISOR_HELPER_COUNT, for example:

cmake -B build -DCMAKE_C_FLAGS=-DRESOLVER_SUPERVISOR_HELPER_COUNT=4
cmake --build build

Usage

mcrelay dumpconfig [-c <config_file> | --config <config_file>]
mcrelay run [-c <config_file> | --config <config_file>]
mcrelay version
mcrelay help [<command>]

The default configuration file is /etc/mcrelay/config.json.

Use mcrelay dumpconfig to parse a configuration file and display its parsed values without starting a server instance.

The program runs in the foreground. Use a service manager such as systemd when it should run as a background service.

Multiple instances can run with separate configuration files as long as their listening addresses do not conflict.

Config

See doc/configuration/mcrelay/config.jsonc for instructions.

Instructions for using DNS-based redirection (SRV)

If you are using an SRV record to provide your service, you should follow the instructions below.

Otherwise, your users will see a message about using an incorrect address to connect.

For example, your SRV record should be like this:

_minecraft._tcp.srvrecord.example.com. => PRIORITY WEIGHT PORT host.example.com

If you provide srvrecord.example.com to your user, you should set your virtual hostname in the configuration file as follows:

• For most Minecraft versions, use host.example.com.
• For Minecraft versions from 21w20a to 1.17, use srvrecord.example.com.

For compatibility, it's recommended to add both of them to your configuration.

IP Forwarding

You can provide the real client address and port through HAProxy's Proxy Protocol by this feature.

It's compatible with any server which supports this protocol (e.g. Bungeecord).

Bungeecord

To use this feature correctly, turn on the proxy_protocol in the config.yml (false to true).