Lite Mode

Ultra-lightweight reverse proxy for hostname-based routing with minimal resource usage

Lite Mode

Gate Lite is an ultra-thin lightweight reverse proxy that efficiently routes client connections based on the hostname the player joins with. This allows you to protect multiple backend servers behind a single port using different domains or subdomains.

Overview

Lite mode makes Gate act as a minimal-overhead reverse proxy between the client and backend servers for host-based connection forwarding. Player connections are offloaded to the destined backend server, including ping requests and player authentication.

Key Features

• Hostname-based routing - Route players based on the domain they connect with
• Minimal overhead - Ultra-lightweight with minimal resource usage
• Multiple backends - Single Gate instance supports multiple backend servers
• Load balancing - Multiple strategies for distributing connections
• Proxy behind proxy - Support for multi-layer proxy setups

Advanced features like backend server switching or proxy commands are not available in Lite mode. Use standard Gate mode if you need these features.

Use Cases

Multi-Server Hosting

Host multiple independent Minecraft servers behind a single IP address:

config:
  lite:
    enabled: true
    routes:
      - host: survival.example.com
        backend: 10.0.0.1:25565
      - host: creative.example.com
        backend: 10.0.0.2:25565
      - host: minigames.example.com
        backend: 10.0.0.3:25565

Players connect to different servers using different domain names, all through port 25565.

Development & Testing

Quickly route localhost connections to different backend servers:

config:
  lite:
    enabled: true
    routes:
      - host: localhost
        backend: localhost:25566
      - host: 127.0.0.1
        backend: localhost:25567

Kubernetes/Cloud Deployments

Dynamically route to backend services using hostname parameters:

config:
  lite:
    enabled: true
    routes:
      # abc.domain.com → abc.servers.svc:25565
      - host: '*.domain.com'
        backend: '$1.servers.svc:25565'

Configuration

Basic Routing

Route connections based on the hostname:

config:
  bind: 0.0.0.0:25565
  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

In this configuration:

• abc.example.com → 10.0.0.3:25568
• Any subdomain of example.com → 10.0.0.1:25567
• example.com or localhost → 10.0.0.2:25566

Hostname Parameter Routing

Extract parts of hostnames using wildcard patterns and use them in backend addresses:

Basic Usage

lite:
  routes:
    # Extract subdomain and use it in backend address
    - host: '*.domain.com'
      backend: '$1.servers.svc:25565'
    # Example: abc.domain.com → abc.servers.svc:25565

lite:
  routes:
    # Capture multiple parts
    - host: '*.*.example.com'
      backend: '$1-$2.servers.svc:25565'
    # Example: abc.def.example.com → abc-def.servers.svc:25565

    # Use parameters in different order
    - host: '*.subdomain.*'
      backend: '$2.$1.backend:25565'
    # Example: abc.subdomain.com → com.abc.backend:25565

lite:
  routes:
    # Using ? for single character matching
    - host: '?.example.com'
      backend: 'server-$1:25565'
    # Example: a.example.com → server-a:25565

Parameter Indexing

• $1 refers to the first wildcard match (* or ?)
• $2 refers to the second wildcard match
• $3 refers to the third wildcard match
• And so on…

Wildcards are numbered in the order they appear in the pattern from left to right.

Wildcard Types

• * matches any sequence of characters (including empty) and captures it
• ? matches any single character and captures it

Gate validates your configuration and will warn you about invalid parameter usage, such as parameters without wildcards or out-of-range parameter indices.

Load Balancing Strategies

When multiple backends are configured, Gate Lite can distribute connections using different strategies:

Sequential (Default)

lite:
  routes:
    - host: play.example.com
      backend: [server1:25565, server2:25565, server3:25565]
      # strategy: sequential # (default - can omit)

lite:
  routes:
    - host: play.example.com
      backend: [server1:25565, server2:25565, server3:25565]
      strategy: random

lite:
  routes:
    - host: lobby.example.com
      backend: [lobby1:25565, lobby2:25565, lobby3:25565]
      strategy: round-robin # Fair rotation

lite:
  routes:
    - host: game.example.com
      backend: [game1:25565, game2:25565, game3:25565]
      strategy: least-connections # Routes to server with fewest active players

lite:
  routes:
    - host: global.example.com
      backend: [us:25565, eu:25565, asia:25565]
      strategy: lowest-latency # Routes to fastest-responding server

Strategy	Description	Algorithm
sequential (default)	Sequential backend order	Tries backends in config order
random	Random backend selection	Cryptographically secure random
round-robin	Sequential cycling	Fair rotation per route
least-connections	Routes to least-loaded backend	Real-time connection counting
lowest-latency	Routes to fastest backend	Status ping latency measurement

Performance Notes:

• All strategies return instantly without health checks
• Failed connections automatically retry next backend
• Latency measurement uses status ping timing for accuracy
• Thread-safe with atomic operations

Ping Response Caching

Gate Lite caches server list ping responses to reduce network traffic:

config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: [10.0.0.3:25565, 10.0.0.4:25565]
        cachePingTTL: 3m # Cache for 3 minutes

Disabling the Cache

Set TTL to -1s to disable response caching:

config:
  lite:
    routes:
      - host: abc.example.com
        backend: 10.0.0.3:25568
        cachePingTTL: -1s # Disable caching

Fallback Status

Define a custom status response when all backends of a route are offline:

config:
  lite:
    enabled: true
    routes:
      - host: localhost
        backend: localhost:25566
        fallback:
          motd: |
            §cLocalhost server is offline.
            §eCheck back later!
          version:
            name: '§cTry again later!'
            protocol: -1

Advanced Features

Modify Virtual Host

Modify the virtual host to match the backend address, useful when backends require specific domains:

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

Lite will modify the player’s handshake packet from localhost → play.example.com before forwarding.

Proxy Behind Proxy

Use another proxy (Gate, BungeeCord, Velocity) as a backend server while preserving real player IP:

config:
  lite:
    enabled: true
    routes:
      - host: abc.example.com
        backend: 10.0.0.3:25566
        proxyProtocol: true # Enable HAProxy PROXY protocol

Ensure the backend proxy also has proxy protocol enabled. See documentation for:

• Gate Proxy Protocol
• Velocity Proxy Protocol
• BungeeCord Proxy Protocol
• Paper Proxy Protocol

Complete Configuration Example

Here’s a complete config-lite.yml example:

config:
  bind: 0.0.0.0:25565
  lite:
    enabled: true
    routes:
      # Simple routing
      - host: localhost
        backend: localhost:25566
        cachePingTTL: 60s
        fallback:
          motd: §cServer offline

      # Wildcard routing
      - host: '*.example.com'
        backend: 172.16.0.12:25566
        proxyProtocol: true

      # Hostname parameter routing
      - host: '*.domain.com'
        backend: '$1.servers.svc:25565'

      # Multiple hosts and backends
      - host: [127.0.0.1, localhost]
        backend: [172.16.0.12:25566, backend.example.com:25566]
        strategy: random
        cachePingTTL: 60s
        modifyVirtualHost: true

      # Catch-all route
      - host: '*'
        backend: 10.0.0.10:25565
        fallback:
          motd: §eNo server available for this host.

  connectionTimeout: 5s
  readTimeout: 30s
  quota:
    connections:
      enabled: true
      ops: 5
      burst: 10
      maxEntries: 1000

Security Considerations

If you use Lite mode and your backend servers handle player authentication, you’re protected by default. For DDoS protection, see the Anti-DDoS guide.

Lite mode forwards authentication to backend servers. Ensure your backends are properly configured for online mode or use proxy protocol for secure setups.