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:
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:
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:
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
.
# 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
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.