BungeeCord Config Creator

What is the BungeeCord config?

This BungeeCord config creator writes config.yml, the one file that decides how a BungeeCord proxy listens for players, which backend servers it knows about, where new players land and who can run proxy commands. Pick a preset or fill in the form above, check the output on the right, and download the file. The rest of this page explains each part of the file, the values most networks should use, and the mistakes that stop a proxy from starting or let players skip it.

BungeeCord is a proxy by md_5, the author of Spigot. Players connect to the proxy, and the proxy connects them on to one of several ordinary Minecraft servers, called backend servers. Moving between those servers with /server or a lobby compass does not disconnect the player, which is what lets a network run a lobby, a survival world and a few minigames as separate servers that feel like one.

BungeeCord creates config.yml in its own folder the first time it starts. The backend servers keep their own server.properties, spigot.yml and plugin configs; the proxy file only covers the network layer on top.

How config.yml is laid out

The file has a handful of top-level keys and three sections that matter most:

You do not need every key in the file. When BungeeCord starts, it reads the file, adds any key that is missing with its default value, and writes the file back. That rewrite also removes any comments you added by hand, so keep notes somewhere else.

Listeners

listeners is a list, so one proxy can listen on several addresses, but almost every network uses a single listener. This tool writes one.

• host is the IP and port the proxy binds to. 0.0.0.0:25577 listens on every network interface on port 25577. Most networks change the port to 25565, the Minecraft default, so players can type the domain without a port.
• motd is the server list message, with & color codes. The MOTD generator shows a live preview of the codes and writes the text for you.
• max_players is only the number shown in the server list. It does not stop anyone from joining. The real cap is the top-level player_limit, which is -1 (no limit) by default.
• tab_list sets what the tab list shows. GLOBAL_PING lists every player on the network with their ping, GLOBAL lists every player without ping, and SERVER shows only the players on the same backend server. tab_size caps the list length.
• ping_passthrough shows the MOTD and player count of the backend server a player would join instead of the proxy's own.
• proxy_protocol reads the real player IP from a HAProxy PROXY header. It is for proxies that sit behind TCPShield, HAProxy or a similar layer-4 proxy. Turned on anywhere else, every connection fails, because the first bytes are a Minecraft handshake and not a PROXY header.
• query_enabled and query_port answer the GameSpy4 query protocol that some server list sites use.

Priorities and force_default_server

priorities replaced the old default_server and fallback_server keys. It is an ordered list of server names. A new player joins the first one; if it is down or full, BungeeCord tries the next. When a player is kicked from a backend server, BungeeCord also uses the list to find somewhere to send them instead of disconnecting them.

With force_default_server: false, a returning player goes back to the server they were on when they left. With true, everyone starts on the first priority server, which is what most lobby-based networks want.

Every name in priorities has to be a key under servers. If one is missing, BungeeCord stops at startup with Server <name> (priority 0) is not defined. The tool warns you when a priority does not match a server in your list.

Forced hosts

forced_hosts maps a domain to a server. A player who connects with skyblock.example.com goes straight to the skyblock server, while play.example.com still follows the priorities list. Each domain needs a DNS record pointing to the proxy; BungeeCord only reads the hostname the client typed.

If forced_hosts is missing from the file, BungeeCord adds a sample entry for pvp.md-5.net. This tool always writes the key, as {} when you add no forced hosts, so the sample never appears. A forced host that points to an unknown server only logs a warning, but players who use that domain end up on the priorities list.

Servers

Each entry under servers is a backend server. The key is the name players type in /server <name> and the name the priorities list and forced hosts refer to.

• address is host:port. On one machine that is 127.0.0.1:25566, 127.0.0.1:25567 and so on; on separate machines it is the private IP of each one. Keep backend ports off the public internet (see the mistakes section below).
• motd is shown when someone pings a forced host for this server and ping_passthrough is off. This tool writes the listener MOTD for every server; edit the lines in the output if you want a different one per server.
• restricted: true hides the server from players who lack the bungeecord.server.<name> permission. It is a simple way to keep a staff or test server private.

BungeeCord needs at least one server to start. It also refuses to reload a config that removes a server, so remove servers with a restart, not a reload.

ip_forward and online mode

This is the part most people get wrong, and it decides both whether players keep their skins and UUIDs and whether the network can be bypassed.

With a proxy, the proxy talks to Mojang, not the backend servers. So the settings split like this:

1. On the proxy: online_mode: true and ip_forward: true.
2. On every backend server: online-mode=false in server.properties, and settings.bungeecord: true in spigot.yml.
3. On Paper backends, also check proxies.bungee-cord.online-mode: true in paper-global.yml so Paper treats players as online-mode accounts.

ip_forward: true sends each player's real IP address and UUID to the backend server. Without it, every player appears to come from the proxy's IP, and the backend server gives them offline-mode UUIDs, so skins break and plugins like LuckPerms store the wrong players. The spigot.yml generator writes the bungeecord: true setting, the server.properties generator writes online-mode=false, and the Paper config generator sets the Paper proxy option.

The catch is that a backend with online-mode=false and bungeecord: true trusts whatever identity arrives in the handshake. If players can reach the backend port directly, they can join as anyone, including an operator. Firewall the backend ports so only the proxy can connect, or bind the backend servers to 127.0.0.1 when they run on the same machine. The BungeeGuard plugin adds a secret token as a second layer.

Other options in this part of the file:

• enforce_secure_profile kicks players whose chat messages are not signed by Mojang, like the same setting in server.properties.
• prevent_proxy_connections sends the player's IP to Mojang during login, so a login made from a different IP (a stolen session) is rejected. It can reject players whose IP changes often.
• reject_transfers refuses players sent over from another server with the transfer packet added in Minecraft 1.20.5.
• forge_support passes the Forge handshake through, for legacy Forge servers up to 1.12.2.

Groups and permissions

BungeeCord has a small permission system built in. permissions defines groups and the permissions each one has, and groups lists players by name with the groups they belong to. By default the default group can use /server and /glist, and the admin group gets /alert, /end, /ip, /greload, /send, /find and the rest. Every player is in default automatically.

groups:
  Notch:
    - admin

The built-in system keys players by name, so a name change loses the permissions, and it has no inheritance or per-server contexts. For anything past a few staff members, install LuckPerms on the proxy and on the backend servers and leave these sections alone. The LuckPerms setup guide covers a network install with a shared database.

disabled_commands turns off proxy commands for everyone, which is handy for hiding /glist or /find on a public network.

Limits, timeouts and logging

• connection_throttle and connection_throttle_limit limit how many connections one IP can make inside the throttle window (4000 ms and 3 by default). BungeeCord checks the connection's own address before it reads any PROXY header, so behind TCPShield or HAProxy every player shares a few addresses. Set connection_throttle: -1 there, as the Behind TCPShield preset does.
• timeout disconnects a player after 30 seconds without network traffic. server_connect_timeout is how long the proxy waits for a backend server when moving a player.
• remote_ping_timeout and remote_ping_cache apply to pings BungeeCord sends to backend servers for ping passthrough and forced hosts. A cache of a few seconds cuts backend load on busy server lists.
• network_compression_threshold compresses packets above 256 bytes. Keep it the same as network-compression-threshold on the backend servers, or set the backends to -1 so the proxy is the only place compression happens.
• log_pings: false stops every server list ping from appearing in the console, which is useful once a network is listed on server list sites.

Recommended values by network type

A proxy uses little memory compared to the game servers; 512 MB to 1 GB is enough for most networks. How much RAM a Minecraft server needs covers the backend servers, and the JVM arguments generator writes start flags for both.

BungeeCord, Waterfall or Velocity?

Waterfall was PaperMC's fork of BungeeCord and read this same config.yml, plus a waterfall.yml of its own. PaperMC has ended Waterfall development, so the Waterfall config creator is there for networks that still run it. For a new network, Velocity is the proxy PaperMC maintains. It has modern forwarding, which signs the forwarded player data with a secret so a backend cannot be joined directly even without a firewall, and it supports the BungeeCord plugin messaging channel that many backend plugins use. The Velocity config builder writes its velocity.toml. BungeeCord itself is still maintained and runs the large library of Bungee plugins, so it remains a fine choice when you depend on one of them.

Common mistakes

1. Backend ports open to the internet. With online-mode=false on the backends, anyone who finds the port can join as any player. Firewall them or bind them to localhost.
2. ip_forward on only one side. ip_forward: true on the proxy needs bungeecord: true in every backend's spigot.yml, and the reverse. A mismatch kicks players with a message about IP forwarding or gives them wrong UUIDs.
3. A priority that is not a server. A typo such as Lobby against a server named lobby works because BungeeCord compares names without case, but hub against lobby stops the proxy at startup.
4. online_mode off on the proxy. That turns the whole network into an offline-mode server. Keep online_mode: true on the proxy.
5. proxy_protocol on without a proxy in front. Every player gets disconnected before login.
6. max_players used as a limit. It only changes the number in the server list; use player_limit.
7. Relying on /greload. Reload cannot remove servers and some changes need a restart anyway. Restart the proxy after editing config.yml.

How to install the generated config.yml

1. Start BungeeCord once with java -Xms512M -Xmx512M -jar BungeeCord.jar so it creates its folder, then type end to stop it.
2. Download config.yml from this tool, or copy the output.
3. Replace config.yml in the BungeeCord folder with it.
4. On each backend server, set online-mode=false and set bungeecord: true in spigot.yml. Restart them.
5. Start BungeeCord and watch the console for Listening on /0.0.0.0:25565 and for YAML or "not defined" errors.
6. Join through the proxy address, run /server to list the servers and switch between them.

For managed hosting, check out ChunkPod.