Skip to content
On this page

Gate Lite Mode

What is Lite mode?

Gate has a Lite mode that makes Gate act as an ultra-thin lightweight reverse proxy between the client and the backend server for host based connection forwarding.

Using different domains or subdomains Lite efficiently routes client connections based on the host address the player joins with. This allows you to protect multiple backend servers behind a single port to a Gate Lite proxy instance.

Player connections are offloaded to the destined backend server, including ping requests and player authentication.

Lite mode supports proxy behind proxy setups, but advanced features like backend server switching or proxy commands are no longer available in this mode and have no effect when extensions use higher level Gate APIs or non-Lite events.

Host based Routing

If you point your domain to the IP address Gate listens on, you can use the domain name as the host address. This allows you to use a single Gate and port for multiple backend servers.

Gate Lite mode routes is a list of host -> backend mappings. For each hostname, Gate will forward the player connection to the first matching backend server.

Graph

In this configuration, Gate Lite will route:

  • Player Bob -> Backend A (10.0.0.1)
  • Player Alice -> Backend B (10.0.0.2)
yaml
config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: 10.0.0.3:25568
      - host: '*.example.com'
        backend: 10.0.0.1:25567
      - host: [ example.com, localhost ]
        backend: [ 10.0.0.2:25566 ]

Ping Response Caching

Players send server list ping requests to Gate Lite to display the motd (message of the day). Gate Lite forwards the actual ping-pong response from the backend server based on the configured route.

If the backend was already pinged some seconds ago Gate Lite directly returns the cached ping response. This reduces the network traffic since less TCP connections must be made to backend servers to fetch the status.

Setting cache duration

To keep and reuse the ping response of a backend for 3 minutes set:

yaml
config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: [ 10.0.0.3:25565, 10.0.0.4:25565 ]
        cachePingTTL: 3m # or 180s 

TTL - the Time-to-live before evicting the response data from the in-memory cache

Note that routes can configure multiple random backends and each backend has its own TTL.

Disabling the cache

Setting the TTL to -1 disables response caching for this route only.

yaml
config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: 10.0.0.3:25568
        cachePingTTL: -1 

Sample config

The Lite configuration is located in the same Gate config.yml file under lite.

yaml
# This is a simplified config where the rest of the
# settings are omitted and will be set by default.
# See config.yml for the full configuration options.
config:
  bind: 0.0.0.0:25565
  # Lite mode is a lightweight reverse proxy mode that acts as thin layer between the client and the backend server.
  # See https://gate.minekube.com/guide/lite
  #
  # It efficiently routes client connections based on the virtual host address received in the handshake packet.
  # This allows to protect multiple backend servers behind a single port Gate Lite proxy instance.
  # Player connections (including ping requests and player authentication) is forwarded to the destined backend server.
  # This means Lite mode supports proxy behind proxy setups, but advanced features like server switching or proxy commands are no longer available
  # and have no effect in Lite mode when extensions use higher level Gate APIs and events.
  lite:
    # Enable Lite mode.
    # If disabled, the proxy will act as a full proxy with all features enabled just like BungeeCord/Velocity.
    # If enabled, the proxy will act as a lightweight reverse proxy to support new types of deployment architecture.
    # Default: false
    enabled: true
    # The routes that the proxy redirects player connections to based on matching the virtual host address.
    # The routes are matched in order of appearance.
    # Examples:
    routes:
      # Match the virtual host address to the backend server.
      - host: localhost
        # The backend server to connect to if matched.
        backend: localhost:25566
      # You can also use * wildcard to match any subdomain.
      - host: '*.example.com'
        backend: 172.16.0.12:25566
        proxyProtocol: true # Use proxy protocol to connect to backend.
        realIP: true # Optionally you can also use TCPShield's RealIP protocol.
      # You can also match to multiple hosts to one or multiple random backends.
      - host: [ 127.0.0.1, localhost ]
        backend: [ 172.16.0.12:25566, backend.example.com:25566 ]
        # Ping responses are cached per backend address by default.
        # To disable motd caching set it to -1.
        # Default: 10s
        cachePingTTL: 60s
      # Match all as last item routes any other host to a default backend.
      - host: '*'
        backend: 10.0.0.10:25565

Proxy behind proxy

Gate Lite mode supports proxy behind proxy setups meaning you can use another proxy like Gate, BungeeCord or Velocity as a backend server.

To preserve the real player IP address you should enable proxyProtocol: true or realIP: true (if using TCPShield) for the route as well as on the backend server.

yaml
config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: 10.0.0.3:25566
        proxyProtocol: true 

Security considerations

If you use Lite mode and your backend servers do player authentication, you do not need to worry.

Checkout the Anti-DDoS guide for how to protect your Minecraft servers from DDoS attacks.

Released under the MIT License. (web version: b1d74095)