# How to Set Up a BungeeCord Network for Your Minecraft Servers (/docs/minecraft/bungeecord-guide) import { Step, Steps } from 'fumadocs-ui/components/steps'; **BungeeCord** is a proxy that sits in front of multiple Minecraft servers, letting players move between them without disconnecting. A typical network has a Lobby, a Survival server, and a few minigame backends — all reachable from a single address. This guide walks through the full setup, from creating the proxy to securing it. > **Modern alternative:** [Velocity](/docs/minecraft/velocity-guide) is the actively-developed successor to BungeeCord. It's faster, more secure, and has better plugin support. Use it for new networks unless you specifically need BungeeCord's plugin ecosystem. How a BungeeCord Network Works [#how-a-bungeecord-network-works] ``` ┌──────────────────────────┐ Players ──── 25565 ─► BungeeCord Proxy │ │ (online-mode: true) │ └─┬──────────┬──────────┬──┘ │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │ Lobby │ │Survival│ │Minigame│ │ 25566 │ │ 25567 │ │ 25568 │ └────────┘ └────────┘ └────────┘ (online-mode: false on all backends) ``` * **Players connect to the proxy** — they never see the backend servers directly * **Proxy authenticates with Mojang** — backends trust the proxy via IP forwarding * **Players use `/server `** to switch between backends without reconnecting What You Need [#what-you-need] | Component | Purpose | | ------------------------------------------ | ------------------------------------------------------- | | **1 BungeeCord proxy server** | Routes players to backends | | **2+ backend Minecraft servers** | Lobby, survival, minigames, etc. | | **BungeeGuard plugin** | Critical security — installed on proxy AND all backends | | **All servers on the same network/region** | Minimize cross-server latency | Step 1: Create the BungeeCord Proxy [#step-1-create-the-bungeecord-proxy] Create a new server with BungeeCord type [#create-a-new-server-with-bungeecord-type] In the [XGamingServer Panel](https://panel.xgamingserver.com), create a new Minecraft server. In **Startup**, set the server type to **BungeeCord** (or select a BungeeCord-compatible Docker image). Start the proxy once to generate config files [#start-the-proxy-once-to-generate-config-files] Start the proxy from **Console**. After it boots, stop it. This creates `config.yml` in the server root. Edit config.yml [#edit-configyml] Click **Files** in the sidebar and open `config.yml`. Replace the `listeners` and `servers` sections: ```yaml listeners: - host: 0.0.0.0:25565 motd: "&aMy Minecraft Network" max_players: 100 priorities: - lobby force_default_server: false bind_local_address: true proxy_protocol: false tab_list: GLOBAL_PING query_enabled: false query_port: 25577 ping_passthrough: false servers: lobby: address: lobby-ip:25566 motd: "&aLobby" restricted: false survival: address: survival-ip:25567 motd: "&2Survival" restricted: false minigames: address: minigames-ip:25568 motd: "&dMinigames" restricted: false ip_forward: true online_mode: true ``` Replace `lobby-ip`, `survival-ip`, `minigames-ip`, and ports with your actual backend addresses from each backend's **Network** tab. Start the proxy [#start-the-proxy] Start the proxy from **Console**. Watch for: ``` [INFO] Listening on /0.0.0.0:25565 ``` Step 2: Configure Each Backend Server [#step-2-configure-each-backend-server] Repeat these steps **on every backend** (lobby, survival, minigames). Stop the backend [#stop-the-backend] Edit server.properties [#edit-serverproperties] Open `server.properties` and set: ```properties online-mode=false ``` > **Critical:** Without `online-mode=false`, the backend will try to authenticate every connection — and reject the proxy. The proxy handles authentication centrally, so backends must trust it. Edit spigot.yml [#edit-spigotyml] Open `spigot.yml` and set: ```yaml settings: bungeecord: true ``` This tells Spigot/Paper to expect BungeeCord forwarding headers. (Paper only) Edit paper-global.yml [#paper-only-edit-paper-globalyml] If running Paper, also set in `config/paper-global.yml`: ```yaml proxies: bungee-cord: online-mode: true ``` Start the backend [#start-the-backend] Start the backend. It should now accept connections from the proxy. Step 3: Install BungeeGuard (Critical Security) [#step-3-install-bungeeguard-critical-security] **Without BungeeGuard, anyone who knows a backend server's IP can connect directly and impersonate any player — including your admins.** This is not optional. Download BungeeGuard [#download-bungeeguard] Get [BungeeGuard](https://www.spigotmc.org/resources/bungeeguard.79601/) from SpigotMC. Install on the proxy [#install-on-the-proxy] Upload `BungeeGuard.jar` to the proxy's `plugins/` folder. Restart the proxy. It generates a token in `plugins/BungeeGuard/config.yml`. Copy the token [#copy-the-token] Open `plugins/BungeeGuard/config.yml` on the proxy and copy the `allowed-tokens` value. Install on each backend [#install-on-each-backend] Upload `BungeeGuard.jar` to each backend's `plugins/` folder. Start the backend once to generate the config, then add the proxy's token to `plugins/BungeeGuard/config.yml`: ```yaml allowed-tokens: - "your-proxy-token-here" ``` Restart each backend. Now backends will reject any connection that doesn't carry the BungeeGuard token — even if someone knows the backend IP. Step 4: Test the Network [#step-4-test-the-network] 1. Connect to the **proxy** address in Minecraft (the address players will use) 2. You should land on the lobby (the first server in `priorities`) 3. Run `/server survival` in chat — you should switch to the survival server without disconnecting 4. Run `/server lobby` to switch back Cross-Server Features [#cross-server-features] | Feature | Plugin | | ------------------------ | --------------------------------- | | Cross-server chat | BungeeChat, LunaChat | | Cross-server economy | LuckPerms + Vault + MySQL backend | | Cross-server permissions | LuckPerms with shared database | | Friends and parties | PartyAndFriends | | Cross-server teleport | BungeeTeleport, RedisBungee | | Lobby selector GUI | BungeePortals, ServerSelector | > **Plugin types:** **BungeeCord plugins** go in the proxy's `plugins/` folder. **Bukkit/Spigot plugins** go in each backend's `plugins/` folder. They are not interchangeable. Common Issues [#common-issues] | Problem | Fix | | --------------------------------------------------- | --------------------------------------------------------- | | "Could not connect to a default or fallback server" | Backend address wrong in `config.yml`, or backend offline | | "If you wish to use IP forwarding..." | `ip_forward: true` missing on proxy | | "Failed to verify username" | Backend has `online-mode=true` — set to `false` | | Players can't switch servers | Server names are case-sensitive — match exactly | | Players see backend IP in client | Use the proxy address, not backend IPs | | Backend rejects proxy connections | BungeeGuard token mismatch — re-copy from proxy config | See [BungeeCord Troubleshooting](/docs/minecraft/bungeecord-troubleshooting) for more. Security Checklist [#security-checklist] * [ ] `online_mode: true` on **proxy** * [ ] `online-mode=false` on **all backends** * [ ] `ip_forward: true` on **proxy** * [ ] `bungeecord: true` in **all backend** `spigot.yml` * [ ] **BungeeGuard installed** on proxy AND all backends * [ ] BungeeGuard token matches across all servers * [ ] Backend ports **firewalled** so they're not directly reachable from the internet Related Guides [#related-guides] * [BungeeCord IP Forwarding](/docs/minecraft/bungeecord-ip-forwarding) * [BungeeCord Troubleshooting](/docs/minecraft/bungeecord-troubleshooting) * [Velocity Guide](/docs/minecraft/velocity-guide) * [BungeeGuard Setup](/docs/minecraft/setup-bungeguard) * [Server Properties](/docs/minecraft/server-properties)