rauks/minecraft-rcon repository overview

⁠Minecraft-RCON

A simple RCON console for Minecraft servers, with a REST API.

⁠Source code

Rauks/Minecraft-RCON-Console (Github)⁠

⁠Usage

⁠Warnings

• Provided as it is, this console has no authentication check, so anybody with access to this console can run any commands on the Minecraft server.
• Please do not expose this console to the internet without any security measures.
• Please consider setting up a reverse proxy with an authentication layer in front of this console, or any other security measures, in order to restrict the access. The following links can help you to find and set up a reverse proxy:
  • Awesome list of reverse proxies⁠
  • Awesome list of identity management⁠
• Use a strong custom random RCON password for more security.

⁠Docker

Below is an example of a docker-compose.yml file to run the Minecraft server and the RCON console:

Please really read the warnings above⁠ before running this example.

services:

  minecraft:
    image: docker.io/itzg/minecraft-server:latest
    container_name: minecraft
    restart: unless-stopped
    environment:
      TYPE: PAPER
      VERSION: latest
      PAPER_CHANNEL: experimental
      EULA: "TRUE"
      ENABLE_RCON: true
      RCON_PASSWORD: ${RCON_PASSWORD}
    tty: true
    stdin_open: true
    volumes:
      - data:/data
    ports:
      - 25565:25565

  rcon:
    image: docker.io/rauks/minecraft-rcon:master
    container_name: minecraft-rcon
    read_only: true
    restart: unless-stopped
    environment:
      # RCON
      RCON_HOST: minecraft
      RCON_PORT: 25575
      RCON_PASSWORD: ${RCON_PASSWORD}
      # Logs
      RUST_LOG: "warn,minecraft_rcon=info"
      # Telemetry (for traces, optional)
      RUST_TRACES: "info"
      OTEL_SERVICE_NAME: "minecraft-rcon"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://grafana-alloy:4317"
    ports:
      - 8888:8888

volumes:
  data:

⁠Environment variables

The following environment variables can be set to configure the backend:

• RCON_HOST: The Minecraft server hostname or IP address. Set to localhost by default.
• RCON_PORT: The Minecraft server RCON port. Set to 25575 by default.
• RCON_PASSWORD: The Minecraft server RCON password. Set to insecure_secret by default, please change it to a strong random password.
• RCON_TIMEOUT: The timeout in milliseconds for the RCON replies waiting. Set to 5000 by default.
• ROCKET_ADDRESS: The address to bind the Rocket server to. Set to 0.0.0.0 by default.
• ROCKET_PORT: The port to bind the Rocket server to. Set to 8888 by default.
• ROCKET_IP_HEADER: The header to use to get the client IP address from the reverse proxy. Set to X-Forwarded-For by default, to be updated depending on your reverse proxy configuration.
• RUST_LOG: The log level for the backend. Set to warn,minecraft_rcon=info by default. See the documentation⁠ for more information about the log levels filtering.
• RUST_TRACES: The trace level for the backend. Set to info by default. See the documentation⁠ for more information about the trace levels filtering.
• OTEL_EXPORTER_OTLP_ENDPOINT: The OpenTelemetry collector endpoint to export the traces to, in the format http://<host>:<port>. If not set, OpenTelemetry tracing will be disabled.
• OTEL_SERVICE_NAME: The OpenTelemetry service name to use for the traces. Set to minecraft-rcon by default.

⁠Common errors

If you encounter an HTTP failure response as shown above when trying to send a command, it means that the backend was not able to send the command to the Minecraft server and get a response. The status code of the error can help you to identify the cause of the problem:

• 502: The backend was unable to connect to the RCON server. Please check the values of the RCON_HOST, RCON_PORT environment variables and make sure that the RCON server is running and accessible from the backend.
• 503: The minecraft server did not respond as expected. Please check the value of the RCON_TIMEOUT environment variable and make sure that the minecraft server is running, not overloaded and can respond to the RCON requests in a timely manner.
• 511: The RCON server refused the connection. Please check the value of the RCON_PASSWORD environment variable and make sure that it matches the RCON password configured on the Minecraft server.

⁠Backend API

⁠API Endpoints

By default, a Swagger UI is available at /swagger-ui to interact with the API.

• POST /api/rcon: The command is sent to the RCON server and the response is returned. The body of the request should be the command to send.

  In case of success, the response will be a JSON object with the key payload containing the response of the RCON server:

  {
    "id": <The generated RCON request id>,
    "payload": <The command reply>
  }
  

  Copy

  In case of error, multiple status codes can be returned:

  • 500 Internal Server Error: Internal error.
  • 502 Bad Gateway: Unable to connect to the RCON server. Please check the values of the RCON_HOST, RCON_PORT environment variables.
  • 503 Service Unavailable: The RCON server did not respond as expected.
  • 511 Network Authentication Required: The RCON server refused the connection. Please check the value of the RCON_PASSWORD environment variable.

• GET /api-docs/openapi.json: OpenAPI endpoint. Returns the OpenAPI⁠ specification of the API.

• GET /metrics: Prometheus metrics endpoint. Returns various metrics about the backend using the OpenMetrics⁠ format. More information about the metrics can be found in the Rocket Prometheus documentation⁠.

⁠Observability

The backend allows multiple observability features to monitor and troubleshoot the RCON requests and the backend itself:

• Metrics⁠ are available at the /metrics endpoint.
• Traces⁠ can be exported to an OpenTelemetry collector (e.g. Grafana Alloy⁠). Requires the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to be set.
• Logs⁠ JSON formatted in stdout.