Infrared - a Minecraft Proxy

An ultra lightweight Minecraft reverse proxy and idle placeholder: Ever wanted to have only one exposed port on your server for multiple Minecraft servers? Then Infrared is the tool you need! Infrared works as a reverse proxy using a subdomain to connect clients to a specific Minecraft server. It works similar to Nginx for those of you who are familiar.

Features

• Reverse Proxy
• Display Placeholder Server
• Autostart Server when pinged
• Logger Callback URLs
• HAProxy Protocol Support
• TCPShield/RealIP Protocol Support
• Prometheus Support
• REST API

Deploy

$ docker build --no-cache -t haveachin/infrared:latest https://github.com/haveachin/infrared.git &&
  docker image prune -f --filter label=stage=intermediate &&
  docker run -d --name infrared --restart=unless-stopped -it -v /usr/local/infrared/configs/:/configs -p 25565:25565/tcp --expose 25565 haveachin/infrared:latest

Update

$ docker build --no-cache -t haveachin/infrared:latest https://github.com/haveachin/infrared.git &&
  docker image prune -f --filter label=stage=intermediate &&
  docker stop infrared &&
  docker rm infrared &&
  docker run -d --name infrared --restart=unless-stopped -it -v /usr/local/infrared/configs/:/configs -p 25565:25565/tcp --expose 25565 haveachin/infrared:latest

Environment Variables

Info: Command-line flags override environment variables.

INFRARED_CONFIG_PATH is the path to all your server configs [default: "./configs/"] INFRARED_RECEIVE_PROXY_PROTOCOL if Infrared should be able to receive proxy protocol [default: "false"]

INFRARED_API_ENABLED if the api should be enabled [default: "false"]
INFRARED_API_BIND change the http bind option [default: "127.0.0.1:8080"]

INFRARED_PROMETHEUS_ENABLED enables the Prometheus stats exporter [default: "false"]
INFRARED_PROMETHEUS_BIND specifies what the Prometheus HTTP server should bind to [default: ":9100"]

Command-Line Flags

-config-path specifies the path to all your server configs [default: "./configs/"]

-receive-proxy-protocol if Infrared should be able to receive proxy protocol [default: false]

-enable-prometheus enables the Prometheus stats exporter [default: false]

-prometheus-bind specifies what the Prometheus HTTP server should bind to [default: :9100]

Example Usage

./infrared -config-path="." -receive-proxy-protocol=true -enable-prometheus -prometheus-bind="localhost:9123"

Proxy Config

Docker

Portainer

More info on Portainer.

Response Status

Player Sample

Callback Server

Examples

Minimal Config

{
  "domainName": "mc.example.com",
  "proxyTo": ":8080"
}

Full Config

{
  "domainName": "mc.example.com",
  "listenTo": ":25565",
  "proxyTo": ":8080",
  "proxyBind": "0.0.0.0",
  "proxyProtocol": false,
  "realIp": false,
  "timeout": 1000,
  "disconnectMessage": "Username: {{username}}\nNow: {{now}}\nRemoteAddress: {{remoteAddress}}\nLocalAddress: {{localAddress}}\nDomain: {{domain}}\nProxyTo: {{proxyTo}}\nListenTo: {{listenTo}}",
  "docker": {
    "dnsServer": "127.0.0.11",
    "containerName": "mc",
    "timeout": 30000,
    "portainer": {
      "address": "localhost:9000",
      "endpointId": "1",
      "username": "admin",
      "password": "foobar"
    }
  },
  "onlineStatus": {
    "versionName": "1.18",
    "protocolNumber": 757,
    "maxPlayers": 20,
    "playersOnline": 2,
    "playerSamples": [
      {
        "name": "Steve",
        "uuid": "8667ba71-b85a-4004-af54-457a9734eed7"
      },
      {
        "name": "Alex",
        "uuid": "ec561538-f3fd-461d-aff5-086b22154bce"
      }
    ],
    "motd": "Join us!"
  },
  "offlineStatus": {
    "versionName": "1.18",
    "protocolNumber": 757,
    "maxPlayers": 20,
    "playersOnline": 0,
    "motd": "Server is currently offline"
  },
  "callbackServer": {
    "url": "https://mc.example.com/callback",
    "events": [
      "Error",
      "PlayerJoin",
      "PlayerLeave",
      "ContainerStart",
      "ContainerStop"
    ]
  }
}

Rest API

The API should not be accessible from the internet!

Enabling API

To enable the API the environment variable INFRARED_API_ENABLED must be set to "true". To change the http bind, set the env variable INFRARED_API_BIND to something like "0.0.0.0:3000" the default value is "127.0.0.1:8080"

API Methods

Create new config

POST /proxies
Body must contain:

{
"domainName": "mc.example.com",
"proxyTo": ":8080"
}

But all values (like in a normal config file) can be set.

The API then will create a file with the name of the domain (if the file exists it will be overwritten) and write the body to it. The proxy can now be visited.

POST /proxies/{fileName}
Body must contain:

{
"domainName": "mc.example.com",
"proxyTo": ":8080"
}

But all values (like in a normal config file) can be set.

The server will create a file with the given filename (if the file exists it will be overwritten) and store the config in it.

Remove config

DELETE /proxies/{fileName}
Replace :file with the name of the proxy configuration file.

If the file was found it will be unloaded and deleted. Open connections do not close, but no new player can connect anymore.

Prometheus exporter

The built-in prometheus exporter can be used to view metrics about infrareds operation.
When the command line flag -enable-prometheus is enabled it will bind to :9100 by default, if you would like to use another port or use an application like node_exporter that also uses port 9100 on the same machine you can change the port with the -prometheus-bind command line flag, example: -prometheus-bind=":9070".
It is recommended to firewall the prometheus exporter with an application like ufw or iptables to make it only accessible by your own Prometheus instance.

Prometheus configuration:

Example prometheus.yml configuration:

scrape_configs:
  - job_name: infrared
    static_configs:
    - targets: ['infrared-exporter-hostname:port']

Metrics:

• infrared_connected: show the amount of connected players per instance and proxy:
  • Example response: infrared_connected{host="proxy.example.com",instance="vps1.example.com:9070",job="infrared"} 10
  • host: listenTo domain as specified in the infrared configuration.
  • instance: what infrared instance the amount of players are connected to.
  • job: what job was specified in the prometheus configuration.
• infrared_proxies: show the amount of active infrared proxies:
  • Example response: infrared_proxies{instance="vps1.example.com:9070",job="infrared"} 5
  • instance: what infrared instance has that amount of active proxies.
  • job: what job was specified in the prometheus configuration.

Coding Guidelines

Commit Messages

When contributing to this project please follow the Conventional Commits specification for writing commit messages, so that changelogs and release versions can be generated automatically.

Example commit message

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Some tooling that can help you author those commit messages are the following plugins:

• JetBrains Plugin Conventional Commit by Edoardo Luppi
• Visual Studio Plugin Conventional Commits by vivaxy

Similar Projects

• https://github.com/itzg/mc-router