# How to Configure IP Forwarding for BungeeCord and Velocity on Minecraft (/docs/minecraft/bungeecord-ip-forwarding)
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
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 [#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 [#set-up-ip-forwarding]
Enable on the proxy [#enable-on-the-proxy]
In the [XGamingServer Panel](https://panel.xgamingserver.com), open **Files** on your BungeeCord proxy and edit `config.yml`. Set:
```yaml
ip_forward: true
```
Save.
Enable on each backend [#enable-on-each-backend]
On every backend Minecraft server, edit `spigot.yml`:
```yaml
settings:
bungeecord: true
```
If you're running **Paper**, also add to `config/paper-global.yml`:
```yaml
proxies:
bungee-cord:
online-mode: true
```
Save.
Set online-mode correctly [#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) [#install-bungeeguard-critical]
Without BungeeGuard, **anyone who knows a backend IP can connect directly and impersonate any player**. Install [BungeeGuard](/docs/minecraft/setup-bungeguard) on the proxy AND every backend, with the same token.
Restart all servers [#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 [#set-forwarding-mode-on-the-proxy]
Open `velocity.toml` on your Velocity proxy:
```toml
player-info-forwarding-mode = "modern"
```
Get the forwarding secret [#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 [#configure-each-paper-backend]
On every Paper backend, edit `config/paper-global.yml`:
```yaml
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 [#set-backend-online-mode]
In each backend's `server.properties`:
```properties
online-mode=false
```
The Velocity proxy handles authentication.
Restart all servers [#restart-all-servers-1]
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 [#how-to-verify-forwarding-works]
After restarting, connect to your proxy and check on a backend:
1. In the backend's **Console**, log in and run:
```
list
```
2. Check the player's IP in `latest.log` — it should be your **real** IP, not `127.0.0.1` or the proxy's IP.
3. Run `/whois ` 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 [#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 [#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 [#related-guides]
* [BungeeCord Setup](/docs/minecraft/bungeecord-guide)
* [BungeeCord Troubleshooting](/docs/minecraft/bungeecord-troubleshooting)
* [Velocity Guide](/docs/minecraft/velocity-guide)
* [BungeeGuard Setup](/docs/minecraft/setup-bungeguard)
* [Failed to Verify Username](/docs/minecraft/fix-failed-verify-username)