How to Configure IP Forwarding for BungeeCord and Velocity on Minecraft
Set up IP forwarding so backend Minecraft servers see real player IPs and UUIDs through a BungeeCord or Velocity proxy.
By default, when a player connects through a BungeeCord or Velocity proxy, the backend server sees the proxy's IP (127.0.0.1 or local) instead of the player's real address. This breaks IP-based bans, region detection, anti-cheat, and any plugin that uses player IPs.
IP forwarding passes the real player IP and UUID through the proxy to the backend, so backends see exactly who's connecting from where.
Forwarding Modes Compared
| Mode | Used by | Security | Notes |
|---|---|---|---|
| Legacy BungeeCord | BungeeCord, older Velocity | ⚠️ Insecure without BungeeGuard | The "classic" mode |
| Modern Velocity | Velocity 1.1+, modern Paper | ✅ Secure (shared secret) | Recommended for new setups |
| Bungeeguard | BungeeCord + plugin | ✅ Secure (shared token) | Use this if you must use BungeeCord |
| None | — | — | Backend sees proxy IP, not player IP |
Set Up IP Forwarding
Enable on the proxy
In the XGamingServer Panel, open Files on your BungeeCord proxy and edit config.yml. Set:
ip_forward: trueSave.
Enable on each backend
On every backend Minecraft server, edit spigot.yml:
settings:
bungeecord: trueIf you're running Paper, also add to config/paper-global.yml:
proxies:
bungee-cord:
online-mode: trueSave.
Set online-mode correctly
| Server | online-mode |
|---|---|
Proxy (config.yml) | online_mode: true |
Backends (server.properties) | online-mode=false |
The proxy authenticates; backends trust the proxy.
Install BungeeGuard (CRITICAL)
Without BungeeGuard, anyone who knows a backend IP can connect directly and impersonate any player. Install BungeeGuard on the proxy AND every backend, with the same token.
Restart all servers
Restart the proxy and every backend. Forwarding only takes effect after a clean restart of both sides.
Velocity's "modern" forwarding mode uses a shared secret, so backends can verify the proxy is genuine — no separate plugin needed. This is the recommended setup for new networks.
Set forwarding mode on the proxy
Open velocity.toml on your Velocity proxy:
player-info-forwarding-mode = "modern"Get the forwarding secret
Velocity generates a random secret in the file forwarding.secret in the server root. Open it and copy the value (it's a single line of random characters).
Configure each Paper backend
On every Paper backend, edit config/paper-global.yml:
proxies:
velocity:
enabled: true
online-mode: true
secret: "paste-the-secret-here"Replace paste-the-secret-here with the exact value from forwarding.secret.
Set backend online-mode
In each backend's server.properties:
online-mode=falseThe Velocity proxy handles authentication.
Restart all servers
Restart Velocity and every Paper backend. Modern forwarding only loads at startup.
Why modern is better: No separate plugin needed, no token to leak, secret is unique per network, and Velocity verifies the secret on every connection. Forge/Fabric backends need extra modules — see Velocity's docs.
How to Verify Forwarding Works
After restarting, connect to your proxy and check on a backend:
- In the backend's Console, log in and run:
list - Check the player's IP in
latest.log— it should be your real IP, not127.0.0.1or the proxy's IP. - Run
/whois <yourname>in any plugin that exposes IPs (LuckPerms, EssentialsX) — same check.
If backends still show 127.0.0.1, forwarding isn't working — see common errors below.
Common Errors
| Error | Cause | Fix |
|---|---|---|
If you wish to use IP forwarding, please enable it in your BungeeCord config | ip_forward: true missing on proxy | Set it, restart proxy |
Your server is not using the modern forwarding mode... | Velocity is set to modern but backend isn't | Set the velocity proxy block in paper-global.yml |
| Players appear with random UUIDs | Forwarding broken — backend can't verify proxy | Restart both sides; verify token/secret matches |
IP shows as 127.0.0.1 on backend | Forwarding not enabled or backend not in BungeeCord mode | Check bungeecord: true in spigot.yml |
Failed to verify username after enabling | Backend online-mode is still true | Set to false on backends, restart |
| Bans by IP not working | IP forwarding off — backend sees proxy IP | Enable forwarding |
Common Mistakes
| Mistake | Fix |
|---|---|
| Restarting only the proxy (not the backends) | Restart both — settings load at startup |
Setting online_mode: false on the proxy | Should be true on the proxy. false on backends only |
| Using BungeeCord legacy forwarding without BungeeGuard | Install BungeeGuard immediately — your network is compromised without it |
| Mismatched Velocity secret | Copy the secret exactly from forwarding.secret — including length |
Mixing Velocity modern + BungeeCord legacy in paper-global.yml | Pick one — never both |
Related Guides
How is this guide?
How to Set Up a BungeeCord Network for Your Minecraft Servers
Build a BungeeCord proxy network linking lobby, survival, and minigame Minecraft servers — with secure IP forwarding and BungeeGuard.
How to Troubleshoot Common BungeeCord Problems on Your Minecraft Network
Fix BungeeCord proxy errors — connection failures, IP forwarding issues, plugin conflicts, authentication problems, and network performance.