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.

In this configuration, Gate Lite will route:

• Player Bob -> Backend A (10.0.0.1)
• Player Alice -> Backend B (10.0.0.2)

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 within the cache window 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:

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 -1s disables response caching for this route only.

config.yml

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

Fallback status for offline backends

If all backends of a route are unreachable, Gate Lite will return a fallback status response if configured. You can utilize all available status fields to customize the response. (See full sample config below.)

config.yml

config:
  lite:
    enabled: true
    routes:
      - host: localhost
        # The backend server to connect to if matched.
        backend: localhost:25566
        # The optional fallback status response when backend of this route are offline.
        fallback:
          motd: |
            §cLocalhost server is offline.
            §eCheck back later!
          version:
            name: '§cTry again later!'
            protocol: -1

Modify virtual host

Modifies the virtual host to match the backend address in the handshake request. This is useful when backends require players to connect with a specific domain to prevent players from using third party domains.

To work around this limitation, simply enable this on your route:

config.yml

config:
  lite:
    enabled: true
    routes:
      - host: localhost
        backend: play.example.com
        modifyVirtualHost: true

Lite will modify the player's handshake packet's virtual host field from localhost -> play.example.com before forwarding the connection to the backend.

Complete Lite config

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

config-lite.yml on GitHub

# 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:
  # The bind address to listen for Minecraft client connections.
  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
        # The optional fallback status response when all backends of this route are offline.
        fallback:
          motd: |
            §cLocalhost server is offline.
            §eCheck back later!
          version:
            name: '§cTry again later!'
            protocol: -1
          # The optional favicon to show in the server list (optimal 64x64).
          # Accepts a path of an image file or the base64 data uri.
          favicon: data:image/png;base64,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
      # 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.
        tcpShieldRealIP: 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
        # Modifies the virtual host to match the backend address in the handshake request.
        # This is useful when backends require players to connect with a specific domain.
        # Lite will modify the player's handshake packet's virtual host field from `localhost` -> `backend.example.com`
        # before forwarding the connection to the backend.
        # Default: false
        modifyVirtualHost: true
      # Match all as last item routes any other host to a default backend.
      - host: '*'
        backend: 10.0.0.10:25565
        fallback:
          motd: §eNo server available for this host.
          version:
            name: §eTry example.com
            protocol: -1
          #favicon: server-icon.png

  # The follow settings from standard Gate also apply to Lite mode.
  #
  # The time Gate waits to connect to a server before timing out.
  connectionTimeout: 5s
  # The time Gate waits to receive data from a server before timing out.
  # If you use Forge, you may need to increase this setting.
  readTimeout: 30s
  # Enabled extra debug logging (only for debugging purposes).
  debug: false
  # Proxy protocol (HA-Proxy) determines whether Gate should support proxy protocol for players.
  # Do not enable this if you don't know what it is.
  proxyProtocol: false
  # The quota settings allows rate-limiting IP (last block cut off) for certain operations.
  # ops: The allowed operations per second.
  # burst: The maximum operations per second (queue like). One burst unit per seconds is refilled.
  # maxEntries: The maximum IPs to keep track of in cache for rate-limiting (if full, deletes oldest).
  quota:
    # Limit how many new connections can be established by the same IP range.
    connections:
      enabled: true
      ops: 5
      burst: 10
      maxEntries: 1000

# Configuration for Connect, a network that organizes all Minecraft servers/proxies
# and makes them universally accessible for all players.
# Among a lot of other features it even allows players to join locally hosted
# Minecraft servers without having an open port or public IP address.
#
# Visit https://connect.minekube.com/
connect:
  # Enabling Connect makes Gate register itself to Connect network.
  # This feature is disabled by default, but you are encouraged to
  # enable it and get empowered by the additional network services
  # and by the growing community in this ecosystem.
  enabled: false
  # The endpoint name is a globally unique identifier of your server.
  # If Connect is enabled, but no name is specified a random name is
  # generated on every restart (only recommended for testing).
  #
  # It is supported to run multiple Gates on the same endpoint name for load balancing
  # (use the same connect.json token file from first Gate instance).
  #name: your-endpoint-name

# Gate HTTP API configuration.
# See https://gate.minekube.com/guide/api for more information.
api:
  # Whether to enable the API for Gate.
  # Default: false
  enabled: false
  # The bind address to listen for API connections.
  # Default: localhost:8080
  bind: localhost:8080

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 tcpShieldRealIP: true (if using Gate behind TCPShield service) for the route as well as on the backend server.

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

• Gate - Enable Proxy Protocol
• Velocity - Enable Proxy Protocol
• BungeeCord - Enable Proxy Protocol
• Paper - Enable Proxy Protocol

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.