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)
BungeeGuard
Legacy
None

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

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:

Install BungeeGuard plugin on backend

Configure plugin:

# plugins/BungeeGuard/config.yml
allowed-tokens:
  - your-secret-here  # Must match Gate's secret

Set backend server.properties:
```
online-mode=false
```

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.

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)

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

BungeeGuard Mode

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

Legacy Mode

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

Backend Server Configuration

Paper/Purpur/Spigot 1.13+

For Velocity mode:

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

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

Edit server.properties:
```
online-mode=false
```
Restart server

Spigot 1.7-1.12

For BungeeGuard mode:

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

For Legacy mode:

Edit spigot.yml:
```
settings:
  bungeecord: true
```
Edit server.properties:
```
online-mode=false
```
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 failedCause: Mismatched secrets between Gate and backendSolution:

Verify secrets match exactly (case-sensitive)
Check for extra whitespace or newlines
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 playersCauses:

Forwarding not enabled on Gate
Backend not configured for forwarding
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 timeCause: Forwarding not working, players get random UUIDsSolution:

Verify forwarding mode is configured correctly
Check secrets match (Velocity/BungeeGuard)
Ensure backend has forwarding enabled
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 joinCause: Backend not receiving real IP addressesSolution: Configure forwarding properlyTest:

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

Join the server

Connect through Gate proxy as normal

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)

Test IP-based features

Try features that depend on player IP:

IP bans
GeoIP plugins
Connection logs

They should work with your real IP

Verify UUID consistency

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

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

Overview

Complete configuration overview

Servers

Configure backend servers

Security

Security best practices and hardening

Online Mode

Understanding online vs offline mode

Get Started

Installation

Core Concepts

Configuration

Features

Security

Player Info Forwarding Configuration

Player Info Forwarding Configuration

Why Forwarding Matters

Configuration

Forwarding Modes

Choosing a Forwarding Mode

Velocity

BungeeGuard

Legacy

None

Secrets Configuration

Velocity Secret

BungeeGuard Secret

Complete Configuration Examples

Velocity Mode (Recommended)

BungeeGuard Mode

Legacy Mode

Backend Server Configuration

Paper/Purpur/Spigot 1.13+

Spigot 1.7-1.12

Vanilla/Fabric/Forge Servers

Security Best Practices

Troubleshooting

Validation and Warnings

Testing Forwarding

Overview

Servers

Security

Online Mode

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Configuration

Features

Security

​Player Info Forwarding Configuration

​Why Forwarding Matters

​Configuration

​Forwarding Modes

​Choosing a Forwarding Mode

Velocity

BungeeGuard

Legacy

None

​Secrets Configuration

​Velocity Secret

​BungeeGuard Secret

​Complete Configuration Examples

​Velocity Mode (Recommended)

​BungeeGuard Mode

​Legacy Mode

​Backend Server Configuration

​Paper/Purpur/Spigot 1.13+

​Spigot 1.7-1.12

​Vanilla/Fabric/Forge Servers

​Security Best Practices

​Troubleshooting

​Validation and Warnings

​Testing Forwarding

​Related Configuration

Overview

Servers

Security

Online Mode

Build docs developers (and LLMs) love

Player Info Forwarding Configuration

Why Forwarding Matters

Configuration

Forwarding Modes

Choosing a Forwarding Mode

Secrets Configuration

Velocity Secret

BungeeGuard Secret

Complete Configuration Examples

Velocity Mode (Recommended)

BungeeGuard Mode

Legacy Mode

Backend Server Configuration

Paper/Purpur/Spigot 1.13+

Spigot 1.7-1.12

Vanilla/Fabric/Forge Servers

Security Best Practices

Troubleshooting

Validation and Warnings

Testing Forwarding

Related Configuration