Set Up BungeeCord: Connect Minecraft Servers Securely

BungeeCord connects multiple Minecraft Java servers behind one public address. The proxy authenticates a player and forwards them to a lobby, survival server, or another backend. It does not host a world itself. A minimal network therefore needs at least two separate processes or hosting instances: one BungeeCord proxy and one Minecraft backend.

The key security rule: backends behind BungeeCord run in offline mode. They must never be freely reachable from the internet. ip_forward: true transports identity; it is not access control. Finish the firewall or private-network protection before calling the network complete.

BungeeCord network architecture

Minecraft Java client
        |
        | public proxy address
        v
 BungeeCord (online_mode=true, ip_forward=true)
        |
        | approved proxy path only
        +---------------------+
        v                     v
 Lobby / Paper          Survival / Paper
 online-mode=false      online-mode=false
 bungeecord=true        bungeecord=true

The proxy owns authentication, the public address, routing, and proxy commands. Backends store worlds, inventories, and Bukkit/Paper plugin data. BungeeCord does not synchronize that data automatically. Network-wide ranks, bans, or inventories require suitable plugins and often a shared database.

Choose the right topology

The BungeeCord configuration looks similar across deployments, but the secure network path does not. Choose the topology before entering addresses in config.yml.

Proxy and backend on the same node

Two hosting instances on one node are still separate containers. The proxy can use the intended internal backend address, while another tenant on the same bridge must remain blocked. Allowing the entire Docker subnet is too broad. Protection must stay bound to the concrete proxy source and re-resolve after a container restart.

Proxy and backend on different nodes

This path crosses the node network. At the backend, allow the exact assigned proxy source and specific TCP port. Do not accidentally expose UDP, a port range, or access from every customer instance behind the node address. Test the positive proxy path and the negative independent path in the same observation window.

External backend

A backend outside the hosting platform needs a route the BungeeCord proxy can reach. The external operator controls its firewall. A reverse tunnel or VPN can provide transport, but is secure only when the backend stays locally bound and the tunnel carries only the authorized proxy path. Do not describe this topology as safe until both positive and negative paths are proven for the concrete setup.

Multiple proxies

Multiple proxies for high availability are a separate design. Every allowed source, shared plugin/data store, and session behavior needs explicit planning. Do not add another IP to a broad allowlist without modeling it. This guide intentionally covers one assigned proxy per backend path.

Requirements and instance model

You need:

• one BungeeCord instance;
• at least one separate Paper/Spigot backend;
• a unique TCP port for each process;
• a network path from the proxy to every backend;
• a firewall, private network, or equivalently verified access control;
• a tested backup before converting an existing server.

At game-serverhosting, BungeeCord is a separate server software choice. Plan the proxy and backends as separate instances. If you do not have them yet, start with Minecraft server hosting. The current BungeeCord source compiles for Java 17; the offered egg runs on Java 21. Do not rely on old blanket capacity claims: plugins, connection rate, compression, and attacks can materially change resource use.

Step 1: Map roles and ports

Give every instance one clear role:

127.0.0.1 only works when proxy and backend share a network namespace. Two Pterodactyl containers on the same host do not automatically share loopback. Use the exact backend address the proxy can reach, and never open an entire container subnet as a shortcut.

Step 2: Back up existing servers

Before changing online mode or forwarding, back up worlds, playerdata, plugin databases, and configuration. Perform at least one test restore. Switching from offline UUIDs to online UUIDs can make players appear new while their old files still exist. The safe version-switch guide explains the backup, clone, and rollback workflow you should also use for this migration.

Step 3: Generate and edit config.yml

Start BungeeCord once, then stop it cleanly. This produces a config.yml matching the installed version. See BungeeCord config.yml explained for the full field guide.

online_mode: true
ip_forward: true
player_limit: -1

servers:
  lobby:
    address: <LOBBY-ADDRESS>:<LOBBY-PORT>
    motd: '&aLobby'
    restricted: false
  survival:
    address: <SURVIVAL-ADDRESS>:<SURVIVAL-PORT>
    motd: '&aSurvival'
    restricted: false

listeners:
  - host: 0.0.0.0:<PROXY-PORT>
    priorities:
      - lobby
      - survival
    force_default_server: true
    max_players: 100

max_players changes the displayed slot count. player_limit is the global hard limit; zero or a negative value means unlimited. Names in priorities must exactly match keys under servers.

Step 4: Configure backend forwarding

On every Paper/Spigot backend:

# server.properties
online-mode=false

# spigot.yml
settings:
  bungeecord: true

For current Paper, also check config/paper-global.yml:

proxies:
  bungee-cord:
    online-mode: true

This Paper value describes the proxy's online mode and should match it. It does not conflict with online-mode=false in server.properties. Set up BungeeCord IP forwarding securely explains the four settings and UUID consequences in detail.

Step 5: Protect backend access

This is the step many older tutorials omit. Allow a backend TCP port only from its assigned proxy or bind it to a genuinely shared private network. An internal-looking IP, restricted: true, or bungeecord: true is not proof of isolation.

At game-serverhosting, the active backend guard derives the permitted proxy path from the concrete proxy instance for supported, verified BungeeCord topologies. If that source is missing or stopped, the path remains drop-only. For an externally operated backend, you must configure its firewall so only the verified proxy path is accepted.

BungeeGuard can add token protection on shared hosting. Use version 1.4.0 or newer; affected older installations must upgrade and rotate their token. Never paste that token into tickets, screenshots, or logs. BungeeGuard complements network protection and does not make a reachable attack surface disappear.

Step 6: Start and test the complete path

Start the backends first and the proxy second. Test more than an open port:

1. The proxy process is running and listening on its allocation.
2. The proxy can reach the lobby address over TCP.
3. Minecraft ping works through the public proxy address.
4. A real test account reaches the lobby and can switch servers.
5. The backend receives the expected IP and online UUID.
6. An independent direct connection to the backend port fails.

Only the sixth check turns working forwarding into a protected result. If entry fails, use the “Could not connect to a default or fallback server” guide without broadly opening the firewall.

Plan routing, fallback, and maintenance

priorities is more than a first-join list. It defines the order BungeeCord tries when a server fails. Put a small, reliably compatible backend first. A survival server with a heavy modpack is rarely the best technical fallback.

forced_hosts can send different domains to different entry targets. For example, creative.example.net can start on creative, while play.example.net starts in the lobby. Both DNS names resolve to the same proxy. Test every hostname because a working default does not reveal a typo in a forced-host mapping.

restricted: true is useful for maintenance or staff servers. Its bungeecord.server.<name> permission is evaluated at the proxy layer. It prevents an ordinary user from switching through BungeeCord, but does not block a direct TCP connection to the backend.

For maintenance:

1. Remove the target from public priorities or restrict it.
2. Move connected players to a healthy backend.
3. Back up and maintain the target.
4. Test proxy-to-backend TCP and a real join.
5. Restore routing only after both pass.

A proxy restart disconnects every player using it. Worlds continue on the backends, but the restart is still a visible interruption and belongs in a maintenance window.

Security review before launch

Review the boundary from an attacker's perspective:

• Is only the proxy documented as the public Minecraft address?
• Is every backend port blocked from an independent workstation?
• Can another instance on the same shared node or bridge reach it?
• Is the current proxy source re-evaluated after stop/start?
• Does a stopped or ambiguous proxy source remain fail-closed?
• Are tokens, complete IPs, and key.pem absent from screenshots and support logs?
• Are commands such as /ip, /send, /alert, and /end limited to necessary roles?
• Are all registered backends trusted? Backends can influence the network through plugin messaging.

If a question cannot be answered by a test or concrete rule, the state is unverified, not “probably safe.” This matters especially on shared hosting: an internal-looking address is not proof of tenant isolation.

Backups, updates, and monitoring

BungeeCord has no world, but its state still matters for recovery. Before updates, back up:

• config.yml and modules.yml;
• proxy plugins/ and their configuration;
• local or external plugin databases consistently;
• the BungeeCord build and Java version in use;
• redacted documentation of backend names, ports, and protection rules.

Worlds, playerdata, and Bukkit/Paper plugin data are backed up separately on backends. A proxy backup is not a world backup. After restoration, verify lobby join, UUID, permissions, and server switching—not just file presence.

For an update, stop the proxy cleanly, replace only the JAR or use the intended installer, and inspect the startup log first. Then test Minecraft ping, real join, identity, fallback, and the still-blocked direct path. Keep the last working JAR and matching configuration as a rollback.

Monitoring should separate at least these signals:

Also observe heap/GC, event-loop stalls, plugin exceptions, backend timeouts, and unusual connection rates. A green dashboard field should not collapse all these states into a generic “online.”

Avoid common setup mistakes

• Proxy and backend ports swapped: players reach the offline-mode backend directly or BungeeCord connects to itself.
• Public domain used as a backend address: the proxy enters a DNS/routing loop. Use the concrete internal target.
• max_players read as a hard limit: the list displays a number while player_limit may remain unlimited.
• Only TCP tested: the listener is open while lobby, forwarding, or protocol still fails.
• Firewall disabled for debugging: the positive join works while an identity bypass remains exposed.
• Bukkit plugin installed on the proxy: platform or dependencies do not match; check the descriptor and project page.
• /greload after deep changes: parts of configuration or plugins remain stale. Perform a full restart.
• Backup without restore test: only an incident reveals that database, world, or plugin state was not captured consistently.

Point domains and SRV at the proxy

DNS always points to the public proxy. For a non-default Java port, an _minecraft._tcp SRV record can publish the port. Its target must be a hostname, not an IP. Follow Connect your own domain for the A/CNAME/SRV steps.

Forced hosts do not change this rule. They use the hostname requested by the client as routing information. survival.example.net still reaches the proxy first; BungeeCord then selects survival internally.

Place plugins and permissions correctly

• BungeeCord plugins belong in the proxy's plugins/ directory.
• Bukkit/Paper plugins belong on the relevant backend.
• Some network plugins require components at both layers.
• Proxy permissions are not automatically available to a backend-only permission plugin.
• A planned full restart is more reliable than /greload after plugin changes.

Use trusted sources and check platform, version, dependencies, and security notices. The Minecraft plugin guide covers Paper/Spigot plugins in the panel; identify proxy plugins explicitly as BungeeCord-compatible.

Add Bedrock crossplay with Geyser

In a BungeeCord network, install Geyser on the proxy, not on every backend. Java uses TCP; the Bedrock listener uses UDP. Floodgate on the proxy is enough unless backend plugins require its API or enhanced skin handling. key.pem is an authentication secret.

Keep TCP and UDP checks separate. Follow the Geyser and Floodgate crossplay guide after the Java-only path is secure.

BungeeCord or Velocity?

BungeeCord was still actively built in 2026. Waterfall, PaperMC's former BungeeCord fork, is end of life. PaperMC recommends Velocity for new networks and explicitly notes that its comparison may favor its own product.

BungeeCord can be the lower-risk choice for an existing network that depends on BungeeCord plugins. For a new network on current Paper versions, Velocity offers Modern Forwarding with a secret and MAC-protected format. Decide on versions, plugin API, forwarding, and migration—not unsupported headline performance numbers. See BungeeCord vs Velocity in 2026 for the full matrix.

FAQ

Is BungeeCord a Minecraft server?

No. It is a proxy. Worlds, chunks, mobs, and game modes run on separate backends.

How many servers do I need?

At least two processes or instances: proxy and backend. A lobby plus one game mode usually means three.

Should the proxy use online mode?

For a normal authenticated network, yes: online_mode: true on the proxy. Backends use online-mode=false because the proxy already authenticated the player.

Is ip_forward secure?

It is required for real IPs and online UUIDs, but is not secure by itself. Legacy forwarding has no proxy-specific signature secret. The backend port must reject untrusted sources.

Does restarting the proxy restart my worlds?

No. Backends keep running, but players connected through the proxy are disconnected.

Do I need a lobby?

Not strictly. You need at least one reachable target in priorities; a dedicated lobby usually makes fallback and maintenance clearer.

Which ports does BungeeCord need?

The public Java listener uses TCP. Every backend needs its own TCP port reachable only from the proxy. Query and Geyser/Bedrock use separate UDP ports when enabled; do not expose them when unused.

Can I install Paper plugins on BungeeCord?

Not generally. Paper/Bukkit plugins belong on backends. The proxy requires plugins built explicitly for BungeeCord. Network plugins may ship two separate components.

Why does the backend see only the proxy IP?

Usually ip_forward on the proxy or settings.bungeecord on the backend is disabled. Check both and fully restart. Back up before changing UUID-relevant settings.

Can I use multiple domains?

Yes. Every domain resolves to the proxy. forced_hosts can then route the requested hostname to an entry backend.

Does crossplay automatically work with every backend?

Geyser translates Bedrock traffic at the proxy. Backends must accept the Java protocol version Geyser emulates; a deliberate ViaVersion setup may be needed across version gaps. Test UDP independently from Java TCP.

Final check

The network is complete only when a real join through the proxy succeeds and an independent direct join to the offline-mode backend is blocked. Document addresses and rules in redacted form, back up proxy configuration and backend worlds separately, and schedule an earlier technical review if BungeeCord, Java, BungeeGuard, Paper, Velocity, or Geyser ships a relevant release.