Player Info Forwarding Configuration

Configure player information forwarding to pass real IPs and UUIDs to backend servers using legacy, velocity, or bungeeguard modes

Player Info Forwarding Configuration

Player info forwarding allows Gate to pass real player information (IP addresses and UUIDs) to backend Minecraft servers. Without forwarding, backend servers only see Gate’s IP address for all players.

Why Forwarding Matters

When players connect through a proxy:

Without forwarding, backend servers:

• See Gate’s IP for all players (breaks IP bans, geolocation)
• Can’t verify player UUIDs (breaks bans, permissions, player data)
• Can’t distinguish between players

With forwarding, backend servers:

• See real player IP addresses
• Get authentic player UUIDs
• Can properly ban, track, and identify players

Configuration

config.forwarding · object

Player information forwarding settings

forwarding:
  mode: velocity
  velocitySecret: your-secret-here

Forwarding Modes

Gate supports multiple forwarding modes for compatibility with different server software:

Velocity (Recommended)

config.forwarding.mode · string

Modern secure forwarding using Velocity’s modern forwarding protocol. Best choice for Paper/Purpur/Spigot 1.13+.

forwarding:
  mode: velocity
  velocitySecret: your-secret-here

Pros:

• ✅ Most secure (uses HMAC authentication)
• ✅ Best performance
• ✅ Widely supported (Paper, Purpur, Spigot 1.13+)
• ✅ No plugin needed

Cons:

• ❌ Not compatible with 1.12.2 and older

Backend Setup:

In backend config/paper-global.yml or paper.yml:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: your-secret-here  # Must match Gate's secret

In backend server.properties:

online-mode=false  # Must be false

BungeeGuard

config.forwarding.mode · string

Secure forwarding for older servers (1.7-1.12.2) using BungeeGuard protocol.

forwarding:
  mode: bungeeguard
  bungeeGuardSecret: your-secret-here

Pros:

• ✅ Secure (uses token authentication)
• ✅ Works with 1.7-1.12.2
• ✅ Better than legacy mode

Cons:

• ❌ Requires plugin on backend
• ❌ Less widely supported than Velocity mode

Backend Setup:

1. Install BungeeGuard plugin on backend
2. Configure plugin:
   # plugins/BungeeGuard/config.yml
   allowed-tokens:
     - your-secret-here  # Must match Gate's secret
   
3. Set backend server.properties:
   online-mode=false
   

Legacy

config.forwarding.mode · string

BungeeCord’s legacy forwarding. Not secure - only use if Velocity mode isn’t supported.

forwarding:
  mode: legacy

Pros:

• ✅ Widely supported (all versions)
• ✅ No backend plugin needed
• ✅ Simple setup

Cons:

• ❌ Not secure - anyone can spoof IPs/UUIDs
• ❌ Backend must trust all connections
• ❌ Only use if backends are on trusted network

Backend Setup:

In backend spigot.yml:

settings:
  bungeecord: true  # Enable BungeeCord mode

In backend server.properties:

online-mode=false

Security Risk: Legacy mode has no authentication. Anyone who can connect to your backend servers can spoof any player’s IP/UUID. Only use on trusted private networks.

None

config.forwarding.mode · string

Disable player info forwarding. Backend servers see Gate’s IP for all players.

forwarding:
  mode: none

Use Cases:

• Testing/development
• Single backend server with no IP-based features
• Backend handles authentication itself

Implications:

• Backend sees Gate’s IP (e.g., 127.0.0.1) for all players
• IP bans won’t work properly
• GeoIP location won’t work
• All players have same “connection IP”

You’ll see a warning on startup: “Player forwarding is disabled! Backend servers will have players with offline-mode UUIDs and the same IP as the proxy.”

Choosing a Forwarding Mode

Use this decision tree:

Velocity

Best for: Modern servers (1.13+)

✅ Most secure
✅ Best performance
✅ Recommended

BungeeGuard

Best for: Older servers (1.7-1.12)

✅ Secure
⚠️ Needs plugin

Legacy

Best for: Trusted networks only

⚠️ Not secure
⚠️ LAN/private only

None

Best for: Testing only

❌ No forwarding
❌ Not recommended

Secrets Configuration

Velocity Secret

config.forwarding.velocitySecret · string

Secret key for Velocity modern forwarding. Must match between Gate and backend servers.

forwarding:
  mode: velocity
  velocitySecret: your-secret-here

Generating a Secret:

# Generate random secret (Linux/macOS)
openssl rand -base64 32

# Or use any random string generator
head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32

# Example output:
RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV

Using Environment Variables (recommended for security):

forwarding:
  mode: velocity
  velocitySecret: ${GATE_VELOCITY_SECRET}  # Read from env var

# Set environment variable
export GATE_VELOCITY_SECRET="RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV"
gate

Or use Gate’s built-in env var support:

export GATE_CONFIG_FORWARDING_VELOCITYSECRET="your-secret"
gate

BungeeGuard Secret

config.forwarding.bungeeGuardSecret · string

Secret token for BungeeGuard forwarding. Must match backend BungeeGuard plugin configuration.

forwarding:
  mode: bungeeguard  
  bungeeGuardSecret: your-secret-here

Configuration:

# Generate secret
openssl rand -base64 32

# Use environment variable
export GATE_BUNGEEGUARD_SECRET="your-secret"

# Or in config

forwarding:
  mode: bungeeguard
  bungeeGuardSecret: ${GATE_BUNGEEGUARD_SECRET}

Complete Configuration Examples

Velocity Mode (Recommended)

Gate config.yml

config:
  bind: 0.0.0.0:25565
  onlineMode: true
  
  servers:
    lobby: localhost:25566
    survival: localhost:25567
  
  try:
    - lobby
  
  # Velocity modern forwarding
  forwarding:
    mode: velocity
    velocitySecret: RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV  # Same as Gate

online-mode=false  # MUST be false with proxy

BungeeGuard Mode

Gate config.yml

config:
  bind: 0.0.0.0:25565
  onlineMode: true
  
  servers:
    lobby: localhost:25566
  
  try:
    - lobby
  
  # BungeeGuard forwarding for 1.7-1.12
  forwarding:
    mode: bungeeguard
    bungeeGuardSecret: your-token-here

allowed-tokens:
  - your-token-here  # Same as Gate

online-mode=false

Legacy Mode

Gate config.yml

config:
  bind: 0.0.0.0:25565
  onlineMode: true
  
  servers:
    lobby: localhost:25566
  
  try:
    - lobby
  
  # Legacy BungeeCord forwarding
  forwarding:
    mode: legacy
    # No secret needed

settings:
  bungeecord: true  # Enable BungeeCord mode

online-mode=false

Backend Server Configuration

Paper/Purpur/Spigot 1.13+

For Velocity mode:

1. Edit config/paper-global.yml (or paper.yml on older versions):

   proxies:
     velocity:
       enabled: true
       online-mode: true
       secret: your-secret-here
   

2. Edit server.properties:

   online-mode=false
   

3. Restart server

Spigot 1.7-1.12

For BungeeGuard mode:

1. Install BungeeGuard
2. Configure plugins/BungeeGuard/config.yml:
   allowed-tokens:
     - your-secret-here
   
3. Edit server.properties:
   online-mode=false
   
4. Restart server

For Legacy mode:

1. Edit spigot.yml:
   settings:
     bungeecord: true
   
2. Edit server.properties:
   online-mode=false
   
3. Restart server

Vanilla/Fabric/Forge Servers

Vanilla servers don’t support forwarding natively. You need:

• Paper/Spigot - Best forwarding support
• Fabric: Install FabricProxy-Lite
• Forge: Use VelocityForge or BungeeGuard equivalent

Security Best Practices

Always use Velocity mode if possible

Velocity modern forwarding is the most secure option:

forwarding:
  mode: velocity  # ✅ Best security
  velocitySecret: strong-random-secret

Avoid legacy mode unless absolutely necessary.

Use strong random secrets

Generate cryptographically secure random secrets:

# ✅ Good - random and long
openssl rand -base64 32

# ❌ Bad - predictable
velocitySecret: "password123"
velocitySecret: "secret"

Store secrets in environment variables

Don’t commit secrets to version control:

# ✅ Good - use environment variable
forwarding:
  velocitySecret: ${GATE_VELOCITY_SECRET}

# ❌ Bad - secret in config file
forwarding:
  velocitySecret: "actual-secret-here"

Add to .gitignore:

config.yml
*.secret

Protect backend servers

Backend servers must ONLY be reachable from Gate:

# Bind backend to localhost only
server-ip=127.0.0.1

Or use firewall rules:

# Only allow connections from Gate IP
iptables -A INPUT -p tcp --dport 25566 -s 10.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 25566 -j DROP

Never use legacy mode on public networks

Legacy mode has no authentication:

# ⚠️ ONLY use on trusted private network
forwarding:
  mode: legacy

Anyone who can connect to your backend can spoof player data.

Troubleshooting

Players can't join - Invalid secret

Error: Connection refused, invalid secret, or authentication failed

Cause: Mismatched secrets between Gate and backend

Solution:

1. Verify secrets match exactly (case-sensitive)
2. Check for extra whitespace or newlines
3. Restart both Gate and backend after changes

# Gate config.yml
velocitySecret: "RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV"

# Backend paper-global.yml - MUST MATCH
secret: "RJf8xZ7kQwH2vY9mL3nP5sN8bG4tE1cV"

Backend sees proxy IP for all players

Problem: Backend logs show Gate’s IP (127.0.0.1) for all players

Causes:

1. Forwarding not enabled on Gate
2. Backend not configured for forwarding
3. Mismatched forwarding modes

Diagnosis:

# Check Gate config
forwarding:
  mode: velocity  # Should NOT be "none"

# Check backend config
# Paper: proxies.velocity.enabled: true
# Spigot: settings.bungeecord: true

Players lose data/inventory after joining

Problem: Players appear as different UUID each time

Cause: Forwarding not working, players get random UUIDs

Solution:

1. Verify forwarding mode is configured correctly
2. Check secrets match (Velocity/BungeeGuard)
3. Ensure backend has forwarding enabled
4. Verify online-mode=false on backend

Check UUIDs are consistent:

# Players should have same UUID each join
grep "UUID of player" backend/logs/latest.log

IP bans not working

Problem: Banned players can still join

Cause: Backend not receiving real IP addresses

Solution: Configure forwarding properly

Test:

# Check backend logs for real player IP
tail -f backend/logs/latest.log
# Should show actual player IP, not proxy IP

Unknown forwarding mode error

Error: Unknown forwarding mode "velocty"

Cause: Typo in config

Valid modes: none, legacy, velocity, bungeeguard

# ❌ Wrong
mode: velocty
mode: modern
mode: bungee

# ✅ Correct
mode: velocity
mode: bungeeguard
mode: legacy

Validation and Warnings

Gate validates forwarding configuration on startup:

# ⚠️ Warning: Forwarding disabled
forwarding:
  mode: none
# Warning: "Player forwarding is disabled! Backend servers will have
#           players with offline-mode UUIDs and the same IP as the proxy."

# ⚠️ Warning: Insecure legacy mode
forwarding:
  mode: legacy
# Warning: "Using legacy forwarding mode! This is not secure.
#           Consider using velocity mode instead."

# ❌ Error: Invalid mode
forwarding:
  mode: invalid
# Error: "Unknown forwarding mode 'invalid', must be one of:
#         none, legacy, velocity, bungeeguard"

Testing Forwarding

Verify forwarding is working:

1. Join the server

   Connect through Gate proxy as normal

2. Check backend logs

   tail -f backend/logs/latest.log
   

   Look for player join message with your real IP:

   [INFO]: Player123[/203.0.113.45:51234] logged in...
   

   Should show your real IP, not proxy’s IP (127.0.0.1)

3. Test IP-based features

   Try features that depend on player IP:

   • IP bans
   • GeoIP plugins
   • Connection logs

   They should work with your real IP

4. Verify UUID consistency

   Join, leave, and rejoin. Your UUID should stay the same:

   grep "UUID of player Player123" backend/logs/latest.log
   

Related Configuration

Overview

Complete configuration overview

Servers

Configure backend servers

Security

Security best practices and hardening

Online Mode

Understanding online vs offline mode